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PREFACE 



The UNIX Programmer's Manual describes most of features of UNIX System 
V. It does not provide a general overview of the UNIX system nor details of 
the implementation of the system. 

Not all commands, features, or facilities described in this series are available in 
every UNIX system implementation. For specific questions on a machine 
implementation of the UNIX system, consult your system administrator. 

The UNIX Programmer's Manual is available in several volumes. 

• Volume 1 contains the Commands and Utilities (sections 1 and 6). 

• Volume 2 contains the System Calls and Library Routines (sections 2, 3, 
4, and 5). 

• Volume 3 contains the System Administration Facilities (section 1M, 7, 
and 8). 
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TRADEMARKS 
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DEC, VAX, PDP, and MASSBUS are trademarks of Digital Equipment Corporation. 
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TEKTRONIX is a registered trademark of Tektronix, Inc. 
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INTRODUCTION 

The UNIX Programmer's Manual Volume 2: System Calls and Library Rou- 
tines is divided into four sections: 

2-System Calls 

3— Library Routines 

4— File Formats 

5— Miscellaneous Facilities 

Section 2 (.System Calls) describes the entries into the UNIX system kernel, 
including the C language interface. 

Section 3 (Library Routines) describes the library routines available on most 
systems. The binary versions usually reside in various system libraries in the 
directories /lib and /usr/lib. See intro(3) for descriptions of these libraries and 
the files in which they are stored. Section 3 is divided into the following 
libraries: 

3C. C and Assembler Library Routines 
3S. Standard I/O Library Routines 
3M. Mathematical Library Routines 
3X. Miscellaneous Routines 
3F. FORTRAN Library Routines 

Section4 (File Formats) documents the structure of particular kinds of files; for 
example, the format of the output of the link editor is given in a.out(4). 
Excluded are files used by only one command. In general, the C language 
struct declarations corresponding to these formats can be found in the direc- 
tories /usr/include and .usr/include/sys. 

Section5 (Miscellaneous Facilities) contains a variety of things. Included are 
descriptions of character sets, macro packages, etc. 
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Each section consists of a number of independent entries of a page or so each. 
The name of the entry appears in the upper corners of its page(s). Entries 
within each section are alphabetized, with the exception of the introductory 
entry that begins each section. Some entries may describe several routines, 
commands, etc. In such cases, the entry appears only once, under its "major" 
name. 

All entries use a common format, not all of whose parts always appear: 

The NAME part gives the name(s) of the entry and briefly states its 
purpose. 

The SYNOPSIS part summarizes the use of the program described. A 
few conventions are used: 



Boldface strings are literals and are typed just as they appear. 



Italic strings usually represent substitutable argument prototypes and 
program names found elsewhere in the UNIX Programmer's Manual. 

Square brackets I 1 around an argument prototype indicate that the 
argument is optional. When an argument prototype is given as "name" 
or "file", it always refers to a file name. 

Ellipses ... are used to show that the previous argument prototype may 
be repeated. 

A final convention is used by the commands themselves. An argument 
beginning with minus — , plus +, or equal sign = is often taken to be a 
flag argument, even if it appears in a position where a file name could 
appear. Files that begin with — , +, or = should therefore be avoided. 

The DESCRIPTION part discusses the subject. 

The EXAMPLE(S) part provides example(s) of usage. 

The FILES part shows the file names that are built into the program. 
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The DIAGNOSTICS part discusses the diagnostic indications that may be pro- 
duced. Messages that are self-explanatory are not listed. 

The BUGS section describes known deficiencies that exist on some implementa- 
tions. 

The SEE ALSO section suggests related utilities or information to consult. 
The WARNINGS part describes potential pitfalls. 

A table of contents and a permuted index precede Section 2. The table of con- 
tents lists each major entry with a brief description and the page number that 
the entry begins on. 

The permuted index is used by searching the middle column for a key word or 
phrase. The right column contains the name of the utility along with the sec- 
tion number. The left column of the permuted index contains additional useful 
information about the utility or command. 

Throughout this volume references to sections 1 and 6 can be found in UNIX 
Programmer's Manual Volume 1: Commands and Utilities. References to 
sections 1M, 7, and 8 will be found in the UNIX Programmer's Manual 
Volume 3: System Administration Facilities. 
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PERMUTED INDEX 



13tol, ltol3: convert between 
long integer and base-64/ 

program. 
Fortran absolute value. 

value. 

abs: return integer 
dabs, cabs, zabs: Fortran 
/floor, ceiling, remainder, 
utime: set file 
accessibility of a file, 
sputl, sgetl: 
ldfcn: common object file 
/setutent, endutent, utmpname: 
access: determine 
enable or disable process 
acct: per-process 
mclock: return Fortran time 
process accounting, 
file format, 
sin, cos, tan, asin, 
intrinsic function, 
formatting/ mosd: the OSDD 
putenv: change or 
imaginary part of complex/ 
part intrinsic function, 
alarm: set a process 
clock. 

change data segment space 
realloc, calloc: main memory 
mallinfo: fast main memory 
natural logarithm/ log, 
logarithm intrinsic/ log 10, 
Fortran/ max, maxO, 
max, maxO, amaxO, maxl, 
Fortran/ min, minO, 
min, minO, aminO, mini, 
remaindering intrinsic/ mod, 
rshift: Fortran Bitwise/ 
Fortran nearest integer/ 
link editor output. 

format, 
acos, dacos: Fortran 
cpio: format of cpio 
ar: common 
header of a member of an 
an archive/ ldahread: read the 
asin, dasin: Fortran 
atan2, datan2: Fortran 
atan, datan: Fortran 
imaginary part of complex 
return Fortran command-line 
varargs: handle variable 
formatted output of a varargs 
formatted output of a varargs 
getopt: get option letter from 
the number of command line 
ascii: map of 
set. 



integer 



3-byte integers and long/ 
a641, 164a: convert between 
abort: generate an IOT fault 
abort: terminate Fortran . 
abs, iabs, dabs, cabs, zabs: 
abs: return integer absolute 

absolute value 

absolute value, abs, iabs, 
absolute value functions. . 
access and modification times 
access: determine 
access long integer data in a/ 
access routines. ...... 

access utmp file entry. . . 
accessibility of a file. . . 
accounting, acct: .... 

accounting file format. . . 

accounting 

acct: enable or disable . . 
acct: per-process accounting 
acos, atan, atan2:/ . . . 
acos, dacos: Fortran arccosine 
adapter macro package for 
add value to environment, 
aimag. dimag: Fortran 
aint, dint: Fortran inte 
alarm clock. 

alarm: set a process alarm 
allocation, brk, sbrk: 
allocator, malloc, free, 
allocator, /calloc, mallopt, 
alog, dloe, clog: Fortran 
aloglO, dlog 10: Fortran common 
amaxO, maxl, amaxl, dmaxl: 
amaxl, dmaxl: Fortran/ . . . 
aminO, mini, aminl, dminl: 
aminl, dminl: Fortran/ . . . 
amod, dmod: Fortran .... 
and, or, xor, not, lshift, . . . 
anint, dnint, nint, idnint: . . . 
a.out: common assembler and . 
ar: common archive file ... 
arccosine intrinsic function. 

archive 

archive file format 

archive file, /the archive . . . 
archive header of a member of 
arcsine intrinsic function. . . 
arctangent intrinsic function. . 
arctangent intrinsic function. . 
argument, /dimag: Fortran 
argument, getarg: ..... 

argument list 

argument list, /print .... 
argument list, /print .... 

argument vector 

arguments, iargc: return . . . 

ASCII character set 

ascii: map of ASCII character 



13tol(3C) 
a641(3C) 
abort(3C) 
abort(3F) 
abs(3F) 
absGC) 
abs(3C) 
abs(3F) 
floor (3M) 
utime(2) 
access (2) 
sputl (3X) 
ldfcn (4) 
getut(3C) 
access (2) 
acct (2) 
acct (4) 
mclock (3 F) 
acct (2) 
acct (4) 
trigQM) 
acos (3 F) 
mosd (5) 
putenv (3 C) 
aimag (3 F) 
aint (3 F) 
alarm (2) 
alarm(2) 
brk(2) 
malloc (3C) 
malloc (3X) 
log(3F) 
loglODF) 
max(3F) 
max(3F) 
min(3F) 
min(3F) 
mod(3F) 
bool(3F) 
round (3 F) 
a.out (4) 
ar(4) 
acos (3 F) 
cpio (4) 
aH4) , 
ldahread (3X) 
ldahread (3X) 
asin (3 F) 
atan2(3F) 
atan (3 F) 
aimag (3 F) 
getarg (3F) 
varargs (5) 
vprintf(3S) 
vprintf(3X) 
getopt(3C) 
iargc(3F) 
ascn(5) 
ascii (5) 
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long integer and base-64 
and/ ctime, localtime, gmtime, 
trigonometric/ sin, cos, tan, 
intrinsic function, 
output, a.out: common 
assertion, 
assert: verify program 
setbuf, setvbuf: 
sin, cos, tan, asin, acos. 
arctangent intrinsic/ 
arctangent intrinsic/ 
cos, tan, asm, acos, atan, 
double-precision/ strtod, 
integer, strtol, atol, 
integer, strtol, 
ungetc: push character 
terminal capability data 
between long integer and 
jO, jl, jn, yO, yl, yn: 
fread, fwnte: 
bsearch: 

tfind, tdelete, twalk: manage 
btest, ibset, ibclr, mvbits: 
/not, lshift, rshift: Fortran 
rshift: Fortran Bitwise 
space allocation, 
sorted table, 
/ieor, ishft, ishftc, ibits. 
stdio: standard 
setbuf, setvbuf: assign 
swab: swap 
value, abs, iabs, dabs, 
data returned by stat system 
malloc, free, realloc, 
fast/ malloc, free, realloc, 
intro: introduction to system 
terminfo: terminal 
pnch: file format for 
function, cos, dcos, 
ceiling, remainder,/ floor, 
/ceil, fmod, fabs: floor, 
intrinsic/ exp, dexp, 
pipe: create an interprocess 
/dole, cmplx, dcmplx, ichar, 
stream, ungetc: push 
and neqn. eqnchar: special 
user, cuserid: get 
/getchar, fgetc, getw: get 
/putchar, fputc, putw: put 
ascii: map of ASCII 
tolower, toascii: translate 
iscntrl, isascii: classify 
directory, 
systems processed by fsck. 
times: get process and 
terminate, wait: wait for 

of a file. 

isgraph, iscntrl, isascii: 
status/ ferror, feof, 
alarm: set a process alarm 



ASCII string, /convert between a641(3C) 

asctime, tzset: convert date . . . ctime (3C) 

asin, acos, atan, atan2: .... trig (3 M) 

asin, dasin: Fortran arcsine . . . asin(3F) 

assembler and link editor . . . a.out (4) 

assert: verify program assert (3X) 

assertion assert (3X) 

assign buffering to a stream. . . setbuf(3S) 

atan, atan2: trigonometric/ . . . trig (3 M) 

atan, datan: Fortran atan (3 F) 

atan2, datan2: Fortran .... atan2(3F) 

atan2: trigonometric/ sin, . . . trig (3 M) 

atof: convert string to strtod (3C) 

atoi: convert string to strtol (3C) 

atol, atoi: convert string to . . . strtol (3C) 

back into input stream ungetc (3S) 

base, terminfo: terminfo (4) 

base-64 ASCII string, /convert . a641(3C) 

Bessel functions . bessel(3M) 

binary input/output fread (3S) 

binary search a sorted table. . . bsearch (3C) 

binary search trees, tsearch, . . tsearch(3C) 

bit field manipulation/ /ibits, . . mil(3F) 

Bitwise Boolean functions. . . . bool(3F) 

Boolean functions, /lshift, . . . bool(3F) 

brk, sbrk: change data segment . brk(2) 

bsearch: binary search a . . . . bsearch (3C) 

btest, ibset, ibclr, mvbits:/ . . . mil(3F) 

buffered input/output package. . stdio(3S) 

buffering to a stream setbuf(3S) 

bytes swab (30 

cabs, zabs: Fortran absolute . . abs(3F) 

call, stat: stat (5) 

calloc: main memory allocator. . malloc(3C) 

calloc, mallopt, mallinfo: .... malloc(3X) 

calls and error numbers. .... intro(2) 

capability data base terminfo (4) 

card images pnch (4) 

ccos: Fortran cosine intrinsic . . cos(3F) 

ceil, fmod, fabs: floor, floor (3 M) 

ceiling, remainder, absolute/ . . floor (3 M) 

cexp:Tortran exponential . . . exp(3F) 

channel pipe (2) 

char: explicit Fortran type/ . . ftypeuF) 

character back into input . . . ungetc (3S) 

character definitions for eqn . . eqnchar (5) 

character login name of the . . cuserid (3S) 

character or word from a/ . . . getc(3S) 

character or word on a stream. . putcuS) 

character set ascii (5) 

characters. / toupper, convuC) 

characters. /Isprint, isgraph, . . ctype(3C) 

chdir: change working chair (2) 

checklist: list of file checklist (4) 

child process times times (2) 

child process to stop or .... wait (2) 

chmod: change mode of file. . . chmod(2) 

chown: change owner and group chown(2) 

chroot: change root directory. . . chrootu) 

classify characters, /isprint, . . ctype(3C) 

clearerr, fileno: stream ferror (3S) 

clock alarm (2) 
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logarithm/ log, alog, dlog, 
ldclose, ldaclose: 
close: 
descriptor, 
fclose, mush: 
/real, float, sngl, dole, 
system: issue a shell 
iargc: return the number of 
system: issue a shell 
getarg: return Fortran 
ar: 

editor output, a.out: 
log 10, alog 10, dlog 10: Fortran 
routines, ldfcn: 
ldopen, ldaopen: open a 
/line number entries of a 
ldclose, ldaclose: close a 
read the file header of a 
entries of a section of a 
the optional file header of a 
/entries of a section of a 
/section header of a 
an indexed/named section of a 
of a symbol table entry of a 
symbol table entry of a 
seek to the symbol table of a 
line number entries in a 
relocation information for a 
scnhdr: section header for a 
/retrieve symbol name for 
table format, syms: 
filehdr: file header for 
ftok: standard interprocess 
lge, lgt, lie, lit: string 
expression, regcmp, regex: 
regexp: regular expression 
term: format of 
erf, erfc: error function and 
Fortran imaginary part of 
conjg, dconjg: Fortran 
table entry of a/ Tdtbindex: 
conjugate intrinsic function, 
conjg, dconjg: Fortran complex 
an out-going terminal line 
math: math functions and 
ioctl: 
fcntl: file 
msgctl: message 
semctl: semaphore 
shmctl: shared memory 
fcntl: file 
terminals, term: 
char: explicit Fortran type 
integers and/ 13tol, ltol3: 
and base-64 ASCII/ a641, 164a: 
/gmtime, asctime, tzset: 
to string, ecvt, fcvt, gcvt: 
scanf, fscanf, sscanf: 
strtod, atof: 
strtol, atol, atoi: 
file. 



clock: report CPU time used. . . clock(3C) 

clog: Fortran natural log(3F) 

close a common object file. . . . ldclose (3X) 

close a file descriptor close (2) 

close: close a file close (2) 

close or flush a stream fclose(3S) 

cmplx, dcmplx, ichar, char:/ . . ftype(3F) 

command from Fortran system(3F) 

command line arguments. . . . iargc(3F) 

command system (3S) 

command-line argument getarg (3 F) 

common archive file format. . . ar(4) 
common assembler and link . . a.out (4) 
common logarithm intrinsic/ . . loel0(3F) 
common object file access . . . ldfcn (4) 
common object file for/ .... ldopen (3X) 
common object file function. . . ldlread(3X) 

common object file ldclose (3X) 

common object file, ldfhread: . . ldfhread(3X) 
common object file, /number . . ldlseek(3X) 
common object file, /seek to . . ldohseek(3X) 

common object file ldrseek(3X) 

common object file ldshread(3X) 

common object file, /seek to . . ldsseek(3X) 
common object file, /the index . ldtbindex(3X) 
common object file, /indexed . . ldtbreaduX) 
common object file, ldtbseek: . . ldtbseek(3X) 
common object file, linenum: . . linenum(4) 
common object file, reloc: . . . reloc(4) 

common object file scnhdr (4) 

common object file symbol/ . . ldgetname(3X) 
common object file symbol . . . syms (4) 

common object files filehdr (4) 

communication package stdipc(3C) 

comparison intrinsic/ strcmp(3F) 

compile and execute regular . . regcmp(3X) 
compile and match routines. . . regexp (5) 

compiled term file termC4) 

complementary error function. . erf (3M) 
complex argument, /dimag: . . aimag(3F) 
complex conjugate intrinsic/ . . conjg(3F) 
compute the index of a symbol . ldtbindex(3X) 
conjg, dconjg: Fortran complex . conjg (3F) 
conjugate intrinsic function. . . coniguF) 
connection, dial: establish . . . dialuC) 

constants math (5) 

control device ioctl (2) 

control fcntl (2) 

control operations msgctl(2) 

control operations semctl (2) 

control operations shmctl (2) 

control options fcntl (5) 

conventional names for .... term (5) 
conversion, /dcmplx, ichar, . . ftype(3F) 
convert between i-byte .... 13tol(3C) 
convert between long integer . . a641(3C) 
convert date and time to/ ... ctime(3C) 
convert floating-point number . . ecvt(3C) 

convert formatted input scanf(3S) 

convert string to/ strtod (3 C) 

convert string to integer strtol (3C) 

core: format of core image . . . core (4) 
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core: format of 
cosine intrinsic function. 
atan2: trigonometric/ sin, 
hyperbolic cosine intrinsic/ 
functions, sinh, 
cos, dcos, ccos: Fortran 
/dcosh: Fortran hyperbolic 
cpio: format of 

clock: report 
rewrite an existing one. 
file, tmpnam, tempnam: 
an existing one. creat: 
fork: 
tmpfile: 
channel, pipe: 
umask: set and get file 
optimization package, curses: 
generate DES encryption, 
function, sin, dsin, 
intrinsic/ sqrt, dsqrt, 
for terminal, 
asctime, tzset: convert date/ 
uname: get name of 
slot in the utmp file of the 
getcwd: get path-name of 
and optimization package, 
name of the user, 
absolute value, abs, iabs, 
intrinsic function, acos, 
intrinsic function, asin, 
terminfo: terminal capability 
/sgetl: access long integer 
plock: lock process, text, or 
call, stat: 
brk, sbrk: change 
types: primitive system 
intrinsic function, atan, 
intrinsic function. atan2, 
/asctime, tzset: convert 
/idint, real, float, sngl, 
/float, sngl, dble, cmplx, 
conjugate intrinsic/ conjg, 
intrinsic function, cos, 
cosine intrinsic/ cosh, 
difference intrinsic/ dim, 
eqnchar: special character 
setkey, encrypt: generate 
device-independent/ font: 
language, troff: 
close: close a file 
dup: duplicate an open file 
file, access: 
master: master 
ioctl: control 
font: description files for 
exponential intrinsic/ exp, 
terminal line connection, 
dim, ddim, idim: positive 
difference intrinsic/ 
of complex argument, aimag, 
intrinsic function, aint, 



core image file 

cos, dcos, ccos: Fortran 
cos, tan, asin, acos, atan, 
cosh, dcosh: Fortran . . 
cosh, tanh: hyperbolic . 
cosine intrinsic function, 
cosine intrinsic function, 
cpio archive. 



cpio: format of cpio archive. 
CP" 



*PU time used, 
creat: create a new file or 
create a name for a temporary 
create a new file or rewrite 
create a new process. . . 
create a temporary file, 
create an interprocess . . 

creation mask 

CRT screen handling and 
crypt, setkey, encrypt: . . 
csin: Fortran sine intrinsic 
csqrt: Fortran square root 
ctermid: generate file name 
ctime, localtime, gmtime, 
current UNIX system. . . 
current user, /find the . . 
current working directory, 
curses: CRT screen handling 
cuserid: get character login 
dabs, cabs, zabs: Fortran . 
dacos: Fortran arccosine . 
dasin: Fortran arcsine . . 

data base 

data in a machine-independent/ 
data in memory. ..... 

data returned by stat system 
data segment space allocation 

data types. 

datan: Fortran arctangent 
datan2: Fortran arctangent . 
date and time to string. . . 
dble, cmplx, dcmplx, ichar,/ 
dcmplx, ichar, char: explicit/ 
dconjg: Fortran complex . 
dcos, ccos: Fortran cosine 
dcosh: Fortran hyperbolic 
ddim, idim: positive . . . 
definitions for eqn and neqn 
DES encryption, crypt, 
description files for . 
description of output 

descriptor 

descriptor 

determine accessibility of a 
device information table 

device 

device-independent troff, 
dexp, cexp: Fortran . 
dial: establish an out-going 
difference intrinsic/ . . 
dim, ddim, idim: positive 
dimag: Fortran imaginary part 
dint: Fortran integer part 



core (4) 
cos(3F) 
trigOM) 
cosh (3 F) 
sinh (3 M) 
cos(3F) 
cosh (3 F) 
cpio (4) 
cpio (4) 
cfockpC) 
creat (2) 
tmpnam (3S) 
creat (2) 
fork (2) 
tmpfile(3S) 
pipe (2) 
umask (2) 
curses (3X) 
crypt (3C) 
sin(3F) 
sqrt (3 F) 
ctermid (3S) 
ctime (3C) 
uname (2) 
ttyslot(3C) 
getcwd(3C) 
curses (3X) 
cuserid (3S) 
abs(3F) 
acos (3 F) 
asin (3 F) 
terminfo (4) 
sputl(3X) 
plock (2) 
stat (5) 
brk(2) 
types (5) 
atan (3 F) 
atan2(3F) 
ctime (3C) 
ftype(3F) 
ftype(3F) 
conig(3F) 
cos(3F) 
cosh(3F) 
dim(3F) 
eqnchar (5) 
crypt(3C) 
font(5) 
troff(5) 
close (2) 
dup (2) 
access (2) 
master (4) 
ioctl (2) 
font (5) 
exp(3F) 
dial(3C) 
dim(3F) 
dim(3F) 
aimag (3 F) 
aint(3F) 
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dir: format of 
chdir: change working 
chroot: change root 
unlink: remove 
path-name of current working 
ordinary file, mknod: make a 
acct: enable or 
hypot: Euclidean 
/lcong48: generate uniformly 
logarithm/ log,- aloe, 
logarithm/ log 10, aloglO, 
max, maxO, amaxO, maxl, amaxl, 
min, minO, aminO, mini, aminl, 
intrinsic/ mod. amod, 
nearest integer/ anint, 
macro package for Tormatting 
macro package for formatting 
intrinsic function, dprod: 
/atof: convert string to 
product intrinsic function. 
nrand48, mrand48, jrand48,/ 
transfer-of-sign/ sign, isign, 
intrinsic function, sin, 
intrinsic function, sinh, 
root intrinsic/ sqrt, 
intrinsic function, tan, 
tangent intrinsic/ tanh, 
descriptor, 
descriptor, dup: 
floating-point number to/ 
program, end, etext, 
common assembler and link 
/user, real group, and 
and/ /getegid: get real user, 
accounting, acct: 
encryption, crypt, setkey, 
setkey, encrypt: generate DES 
locations in program, 
/getgrgid, getgrnam, setgrent, 
/getpwuid, getpwnam, setpwent, 
utmp/ /pututline, setutent, 
nlist: get 

file, linenum: line number 
man: macros for formatting 
file/ /manipulate line number 
/ldnlseek: seek to line number 
/ldnrseek: seek to relocation 
utmp, wtmp: utmp and wtmp 
fgetgrent: get group file 
fgetpwent: get password file 
utmpname: access utmp file 
object file symbol table 
/the index of a symbol table 
/read an indexed symbol table 
putpwent: write password file 
unlink: remove directory 

profile: setting up an 
environ: user 
getenv: return value for 
putenv: change or add value to 



dir: format of directories. . . . 

directories 

directory 

directory 

directory entry 

directory, getcwd: get 

directory, or a special or .... 
disable process accounting. . . . 

distance function 

distributed pseudo-random/ . . 
dlog, clog: Fortran natural . . . 
dloglO: Fortran common . . . . 
dmaxl: Fortran maximum-value/ 
dminl: Fortran minimum-value/ 
dmod: Fortran remaindering 
dnint, nint, idnint: Fortran 
documents, mm: the MM 
documents, /the OSDD adapter 
double precision product . . 
double-precision number, 
dprod: double precision . . 
drand48, erand48, lrand48, . 

dsign: Fortran 

dsin, csin: Fortran sine . . 
dsinh: Fortran hyperbolic sine 
dsqrt, csqrt: Fortran square 
dtan: Fortran tangent . . . 
dtanh: Fortran hyperbolic 
dup: duplicate an open file . 
duplicate an open file 
ecvt, fcvt, gcvt: convert 
edata: last locations in . 
editor output, a.out: . . 
effective group IDs. . . 
effective user, real group, 
enable or disable process 
encrypt: generate DES 
encryption, crypt, . . . 
end, etext, edata: last . 
endgrent, fgetgrent: get group/ 
endpwent, fgetpwent: get/ 
endutent, utmpname: access 
entries from name list. . . 
entries in a common object 
entries in this manual. . . 
entries of a common object 
entries of a section of a/ . 
entries of a section of a/ . 

entry formats 

entry, /setgrent, endgrent, 
entry, /setpwent, endpwent, 
entry, /setutent, endutent, 
entry, /symbol name for common 
entry of a common object file, 
entry of a common object file. 

entry 

entry 

environ: user environment. . . . 
environment at login time. . . . 

environment 

environment name 

environment . 



dir(4) 

dir(4) 

chdir (2) 

chroot (2) 

unlink (2) 

getcwd (3C) 

mknod (2) 

acct (2) 

hypot (3M) 

drand48(3C) 

log(3F) 

logl0(3F) 

maxuF.) 

min(3F) 

mod(3F) 

round (3 F) 

mm (5) 

mosd(5) 

dprod (3 F) 

strtodGC) 

dprod (3 F) 

drand48(3C) 

sign (3 F) 

sin(3F) 

sinh (3 F) 

sqrt (3 F) 

tan(3F) 

tanh (3 F) 

dup(2) 

dup(2) 

ecvt(3C) 

end(3C) 

a. out (4) 

getuid(2) 

getuid(2) 

acct (2) 

crypt (3C) 

crypt (3C) 

end(3C) 

getgrent(3C) 

getpwentuC) 

getut(3C) 

nlist(3C) 

linenum (4) 

man (5) 

ldlread(3X) 

ldlseek(3X) 

ldrseek(3X) 

utmp (4) 

getgrent(3C) 

getpwent(3C) 

getut(3C) 

Idgetname(3X) 

ldtbindexOX) 

ldtbread(3X) 

putpwent (3 C) 

unhnk(2) 

environ (5) 

profile (4) 

environ (5) 

getenv (3C) 

putenv (3C) 
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getenv: return Fortran 
character definitions for 
definitions for eqn and neqn. 
mrand48, jrand48,/ drand48, 
complementary error function, 
complementary error/ erf, 
format, 
system error/ perror, 
complementary/ erf, erfc: 
function and complementary 
sys_errlist, sys_nerr: system 
to system calls and 
matherr: 
errfile: 

terminal line/ dial: 
in program, end, 
hypot: 

execlp, execvp: execute a/ 
execvp: execute/ execl, execv, 
execl, execv, execle, execve, 
execve, execlp, execvp: 
regcmp, regex: compile and 
sleep: suspend 
monitor: prepare 
profil: 

execvp: execute a/ execl, 
execute/ execl, execv, execle, 
/execv, execle, execve, execlp, 
a new file or rewrite an 
process, 
exit. 

exponential intrinsic/ 
exponential, logarithm,/ 
cmplx, dcmplx, icnar, char: 
exp, dexp, cexp: Fortran 
exp, log, log 10, pow, sqrt: 
routines, regexp: regular 
compile and execute regular 
remainder,/ floor, ceil, fmod, 
data in a machine-independent 
/calloc, mallopt, mallinfo: 
abort: generate an IOT 
a stream. 



floating-point number/ ecvt, 
fopen, freopen, 
status inquiries, ferror, 
fileno: stream status/ 
stream, fclose, 
word from a/ getc, getchar, 
/getgrnam, setgrent, endgrent, 
/getpwnam, setpwent, endpwent, 
stream, gets, 
times, utime: set 
ldfcn: common object 
determine accessibility of a 
chmod: change mode of 
change owner and group of a 
fcntl: 
fcntl: 

core: format of core image 



environment variable getenv (3 F) 

eqn and neqn. /special .... eqnchar(5) 

eqnchar: special character . . . eqnchar(5) 

erand48, lrand48, nrand48, . . . drand48(3C) 

erf, erfc: error function and . . erf(3M) 

erfc: error function and .... erf(3M) 

errfile: error-log file ...... errfile (4) 

errno, sys errlist, sys nerr: . . . perror(3C) 

error function and erf(3M) 

error function, /erfc: error . . . erf(3M) 

error messages, /errno, .... perror (3 C) 

error numbers, /introduction . . intro(2) 

error-handling function matherr (3 M) 

error-log file format errfile (4) 

establish an out-going dial (3 C) 

etext, edata: last locations . . . end(3C) 

Euclidean distance function. . . hypot (3M) 

execl, execv, execle, execve, . . exec (2) 

execle, execve, execlp, exec (2) 

execlp, execvp: execute a/ ... exec (2) 

execute a file, /execle, exec (2) 

execute regular expression. . . . regcmp(3X) 

execution For interval sleepuC) 

execution profile monitor(3C) 

execution time profile profil (2) 

execv, execle, execve, execlp, . . exec (2) 

execve, execlp, execvp: exec (2) 

execvp: execute a file exec (2) 

existing one. creat: create . . . creat(2) 

exit, exit: terminate exit (2) 

exit: terminate process exit (2) 

exp, dexp, cexp: Fortran .... exp(3F) 

exp. log, loglO, pow, sqrt: . . . exp(3M) 

explicit Fortran type/ /dble, . . ftype(3F) 

exponential intrinsic/ exp(3F) 

exponential, logarithm, power,/ . exp(3M) 

expression compile and match . regexp (5) 

expression, regcmp, regex: . . . regcmp (3X) 

fabs: floor, ceiling, floor (5M) 

fashion., /access long integer . . sputl(3X) 

fast main memory allocator. . . malloc(3X) 

fault abort (3C) 

fclose, fflush: close or flush . . . fclose (3S) 

fcntl: file control fcntl (2) 

fcntl: file control options fcntl (5) 

fcvt, gcvt: convert ecvt(3C) 

fdopen: open a stream fopen (3S) 

feoi, clearerr, fileno: stream . . ferror (3S) 

ferror, feof, clearerr, ferror(3S) 

fflush: close or flush a fclose (3 S) 

fgetc, getw: get character or . . getc(3S) 

fgetgrent: get group file/ .... getgrent(3C) 

fgetpwent: get password file/ . . getpwent(3C) 

fgets: get a string from a . . . . gets(3S) 

file access and modification . . . utime (2) 

file access routines ldfcn (4) 

file, access: . access (2) 

file chmod (2) 

file, chown: chown(2) 

file control fcntl(2) 

file control options . fcntl(5) 

file core (4) 
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umask: set and get file creation mask umask(2) 

close: close a file descriptor close (2) 

dup: duplicate an open file descriptor dup (2) 

endgrent, fgetgrent: get group file entry, /setgrent, getgrentOO 

fgetpwent: get password file entry, /endpwent, getpwent(3C) 

utmpname: access utmp file entry, /endutent, getut(3C) 

putpwent: write password file entry putpwent(3C) 

execlp, execvp: execute a file, /execv. execle, execve, . . . exec (2) 

ldaopen: open a common object file for reading, ldopen, .... ldopen(3X) 

acct: per-process accounting file format acct(4) 

ar: common archive file format ar(4) 

errfile: error-log file format errfile(4) 

pnch: file format for card images. . . pnch(4) 

intro: introduction to file formats intro (4) 

entries of a common object file function, /line number . . . ldlread(3X) 

group: group file group (4) 

files, filehdr: file header for common object . filehdr (4) 

file, ldfhread: read the file header of a common object . ldfhread (3X) 

ldohseek: seek to the optional file header of a common object/ . ldohseek(3X) 

issue: issue identification file issue (4) 

of a member of an archive file, /read the archive header . . ldahread(3X) 

close a common object file. Idclose, ldaclose: ldclose(3X) 

file header of a common object file, ldfhread: read the .... ldfhread (3X) 

a section of a common object file, /line number entries of . . ldlseek(3X) 

file header of a common object file, /seek to the optional . . . ldohseek(3X) 

a section of a common object file, /relocation entries of ... ldrseek(3X) 

header of a common object file, /indexed/named section . . ldshread(3X) 

section of a common object file, /to an indexed/named . . . ldsseek(3X) 

table entry of a common object file, /the index of a symbol . . ldtbindex(3X) 

table entry of a common object file, /read an indexecf symbol . . ldtbreaduX) 

table of a common object file, /seek to the symbol .... ldtbseek(3X) 

entries in a common object file, linenum: line number . . . linenum(4) 

link: link to a file link(2) 

or a special or ordinary file, /make a directory, .... mknod(2) 

ctermid: generate file name for terminal. ctermiduS) 

mktemp: make a unique file name mktemp(3C) 

/find the slot in the utmp file of the current user ttysloU3C) 

one. creat: create a new file or rewrite an existing . . . creat(2) 

passwd: password file passwd(4) 

/rewind, ftell: reposition a file pointer in a stream fseek(3S) 

lseek: move read/ write file pointer lseek(2) 

read: read from file read (2) 

for a common object file, /relocation information . . reloc(4) 

sccsfile: format of SCCS file sccsfile (4) 

header for a common object file, scnhdr: section scnhdr(4) 

stat, fstat: get file status stat(2) 

/symbol name for common object file symbol table entry ldgetname(3X) 

syms: common object file symbol table format syms(4) 

volume, file system: format of system . . fs(4) 

mount: mount a file system mount (2) 

ustat: get file system statistics ustat (2) 

mnttab: mounted file system table mnttab (4) 

umount: unmount a file system umount(2) 

fsck. checklist: list of file systems processed by ... . checklist (4) 

term: format of compiled term file term (4) 

tmpfile: create a temporary file tmpfile(3S) 

create a name for a temporary file, tmpnam, tempnam: .... tmpnam(3S) 

ftw: walk a file tree ftw(3C) 

write: write on a file write(2) 

common object files, filehdr: file header for filehdr (4) 

ferror, feof, clearerr, fileno: stream status/ ferror(3S) 

file header for common object files, filehdr: filehdr (4) 
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troff. font: description 
format specification in text 
string, format of graphical 
lockf: record locking on 
ttyname, isatty: 
of the current user, ttyslot: 
int, ifix, idint, real, 
ecvt, fcvt, gcvt: convert 
/modf: manipulate parts of 
floor, ceiling, remainder,/ 
floor, ceil, fmod, fabs: 
fclose, fflush: close or 
remainder,/ floor, ceil, 
device-independent troff. 

stream. 

per-process accounting file 
ar: common archive file 
errfile: error-log file 
pnch: file 
inode: 
term: 
core: 
cpio: 
dir: 

/graphical primitive string, 
sccsfile: 
file system: 
files, fspec: 
object file symbol table 
intro: introduction to file 
wtmp: utmp and wtmp entry 
scanf, fscanf, sscanf: convert 
/vfprintf, vsprintf: print 
/vfprintf, vsprintf: print 
fprintf, sprintf: print 
mptx: the macro package for 
mm: the MM macro package for 
OSDD adapter macro package for 
manual, man: macros for 
abs, iabs, dabs, cabs, zabs: 
system/ signal: specify 
function, acos, dacos: 
function, asin, dasin: 
function. atan2, datan2: 
function, atan, datan: 
or, xor, not, lshift, rshift: 



files for device-independent 
files, fspec: 

files, /graphical primitive 
files. 



getarg: return 
), aloj 



log 10, aloglO, dloglO: 
intrinsic/ conjg, dconjg: 
function, cos, dcos, ccos: 
getenv: return 
function, exp, dexp, cexp: 
intrinsic/ cosh, dcosh: 
intrinsic/ sinh, dsinh: 
intrinsic/ tanh, dtanh: 
complex/ aimag, dimag: 
function, aint, dint: 
amaxO, maxl, amaxl, dmaxl: 
/and subroutines from the 
aminO, mini, aminl, dminl: 
log, alog, dlog, clog: 



find name of a terminal. . 
find the slot in the utmp file 
floatj sngl, dble, cmplx,/ . 
floating-point number to/ 
floating-point numbers, 
floor, ceil, fmod, fabs: . . 
floor, ceiling, remainder,/ 

flush a stream 

fmod, fabs: floor, ceiling, . 
font: description files for . 
fopen, freopen, fdopen: open 
fork: create a new process, 
format, acct: .... 

format 

format 

format for card images, 
format of an i-node. . 
format of compiled term file 
format of core image file, 
format of cpio archive, 
format of directories. . . 
format of graphical files. . 
format of SCCS file. . . 
format of system volume, 
format specification in text 
format, syms: common 

formats 

formats, utmp, 

formatted input 

formatted output of a varargs/ 
formatted output of a varargs/ 
formatted output, printf, . 
formatting a permuted index 
formatting documents. . . 
formatting documents, /the 
formatting entries in this . 
Fortran absolute value. 
Fortran action on receipt of a 
Fortran arccosine intrinsic 
Fortran arcsine intrinsic . 
Fortran arctangent intrinsic 
Fortran arctangent intrinsic 
Fortran Bitwise Boolean/ and, 
Fortran command-line argument. 
Fortran common logarithm/ 
Fortran complex conjugate . . 
Fortran cosine intrinsic . . . 
Fortran environment variable. 
Fortran exponential intrinsic . 
Fortran hyperbolic cosine . . 
Fortran hyperbolic sine . . . 
Fortran hyperbolic tangent . . 
Fortran imaginary part of . . 
Fortran integer part intrinsic . 
Fortran maximum-value/ /maxO 
Fortran Military Standard/ 
Fortran minimum-value/ /minO, 
Fortran natural logarithm/ . . 



font (5) 

fspec (4) 

gps(4) 

IockfUC) 

ttyname(3C) 

ttyslotOC) 

ftype(3F) 

ecvt (30 

frexp(3C) 

floor(3M) 

floor(3M) 

fclose(3S) 

floor(3M) 

font(5) 

fopen (3S) 

fork(2) 

acct (4) 

ar(4) 

errfile (4) 

pnch (4) 

mode (4) 

term (4) 

core(4) 

cpio (4) 

dir(4) 

gps(4) 

sccsfile (4) 

fs(4) v 

fspec (4) 

syms (4) 

intro (4) 

utmp (4) 

scanf(3S) 

vprintf(3S) 

vprintf(3X) 

printf(3S) 

mptx(5) 

mm (5) 

mosd(5) 

man (5) 

abs(3F) 

signal (3 F) 

acos(3F) 

asin (3 F) 

atan2(3F) 

atan(3F) 

bool(3F) 

getarg(3F) 

Fogl0T3F) 

conjg (3 F) 

cosuF) 

getenv (3 F) 

exp(3F) 

cosh(3F) 

sinh(3F) 

tanh (3 F) 

aimag (3 F) 

aint (3 F) 

max(3F) 

mil(3F) 

min(3F) 

log(3F) 
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anint, dnint, nint, idnint: 
abort: terminate 
functions, mod, amod, dmod: 
function, sin, dsm, csin: 
function, sqrt, dsqrt, csqrt: 
len: return length of 
index: return location of 
issue a shell command from 
function, tan, dtan: 
mclock: return 
intrinsic/ sign, isign, dsign: 
/dcmplx, ichar, char: explicit 
formatted output, printf, 
word on a/ putc, putchar, 
stream, puts, 
input/output, 
memory allocator, malloc, 
mallopt, mallinfo:/ malloc, 
stream, fopen. 
parts of floating-point/ 
getw: get character or word 
gets, fgets: get a string 
getopt: get option letter 
read: read 

system: issue a shell command 
nlist: get entries 
/functions and subroutines 
getpw: get name 
formatted input, scanf, 
of file systems processed by 
reposition a file pointer in/ 
text files, 
stat, 

pointer in a/ fseek, rewind, 
communication package. 

Fortran arccosine intrinsic 
Fortran integer part intrinsic 
error/ erf, erfc: error 
Fortran arcsine intrinsic 
Fortran arctangent intrinsic 
Fortran arctangent intrinsic 
complex conjugate intrinsic 
ccos: Fortran cosine intrinsic 
hyperbolic cosine intrinsic 
precision product intrinsic 
and complementary error 
Fortran exponential intrinsic 
gamma: log gamma 
hypot: Euclidean distance 
of a common object file 
common logarithm intrinsic 
natural logarithm intrinsic 
matherr: error-handling 
prof: profile within a 
transfer-of-sign intrinsic 
csin: Fortran sine intrinsic 
hyperbolic sine intrinsic 
Fortran square root intrinsic 
Fortran tangent intrinsic 
hyperbolic tangent intrinsic 
math: math 



Fortran nearest integer/ .... round (3 F) 

Fortran program abort (3 F) 

Fortran remaindering intrinsic . mod(3F) 

Fortran sine intrinsic sin(3F) 

Fortran square root intrinsic . . sqrt (3 F) 

Fortran string len(3F) 

Fortran substring index (3 F) 

Fortran, system: system (3 F) 

Fortran tangent intrinsic .... tan(3F) 

Fortran time accounting mclock(3F) 

Fortran transfer-of-sign .... sign (3 F) 

Fortran type conversion ftype(3F) 

fprintf, sprintf: print printf (3S) 

route, putw: put character or . . putc(3S) 

fputs: put a string on a .... puts(3S) 

fread, Twrite: binary fread (3S) 

free, realloc, calloc: main . . . malloc(3C) 

free, realloc, calloc, malloc(3X) 

freopen, fdopen: open a .... fopen(3S) 

frexp, ldexp, modi: manipulate . frexp(3C) 

from a stream, /fgetc, getc(3S) 

from a stream gets(3S) 

from argument vector getopt (3C) 

from file read (2) 

from Fortran system(3F) 

from name list nlist (3C) 

from the Fortran Military/ . . . mil(3F) 

from UID getpw (3C) 

fscanf, sscanf: convert scanfuS) 

fsck. checklist: list checklist (4) 

fseek, rewind, ftell: fseek(3S) 

fspec: format specification in . . fspecU) 

fstat: get file status . stat (2) 

ftell: reposition a file fseek (3S) 

ftok: standard interprocess . . . stdipc(3C) 

ftw: walk a file tree ftw(3C) 

function, acos, dacos: acos(3F) 

function, aint, dint: aint(3F) 

function and complementary . . erf(3M) 

function, asin, dasin: asin(3F) 

function. atan2, datan2: .... atan2(3F) 

function, atan, datan: atan(3F) 

function, /dconjg: Fortran . . . conig(3F) 

function, cos, dcos, cosuF) 

function, /dcosh: Fortran . . . cosh(3F) 

function, dprod: double .... dprod(3F) 

function, /error function .... erf(3M) 

function, exp, dexp, cexp: . . . exp(3F) 

function gamma (3M) 

function hypot (3 M) 

function, /line number entries . ldlread(3X) 

function. /dloglO: Fortran . . . log 10 (3 F) 

function, /dlog, clog: Fortran . . log(3F) 

function matherr (3 M) 

function prof (5) 

function, /dsign: Fortran . . . sign (3 F) 

function, sin, dsin, sin(3F) 

function, /dsinh: Fortran . . . sinh(3F) 

function, sqrt, dsqrt, csqrt: . . . sqrt(3F) 

function, tan, dtan: tan(3F) 

function, /dtanh: Fortran . . . tanh(3F) 

functions and constants math (5) 



UNIX Programmer's Manual 



System Calls and Library Routines— xxi 



/field manipulation intrinsic 
jO, jl, jn, yO, yl, yn: Bessel 
Fortran Bitwise Boolean 
positive difference intrinsic 
logarithm, power, square root 
remainder, absolute value 
dmaxl: Fortran maximum-value 
dminl: Fortran minimum-value 
Fortran remaindering intrinsic 
Fortran nearest integer 
sinh, cosh, tanh: hyperbolic 
string comparison intrinsic 
atan, atan2: trigonometric 
fread, 
gamma: log 

number to string, ecvt, fcvt, 
abort: 

crypt, setkey, encrypt: 
terminal, ctermid: 
/srand48, seed48, lcong48: 
srand: simple random-number 
rand, srand: random number 
gets, fgets: 
uhmit: 
the user, cuserid: 
getc, getchar, fgetc, getw: 
nlist: 

umask: set and 
stat, fstat: 
ustat: 

/setgrent, endgrent, fgetgrent: 
gettogin: 
msgget: 
getpw: 
system, uname: 
argument vector, getopt: 
/setpwent, endpwent, fgetpwent: 
working directory, getcwd: 
times, times: 
and/ getpid, getpgrp, getppid: 
/geteuid, getgid, getegid: 
semget: 
shmget: 
time: 

command-line argument, 
get character or word From a/ 
character or word from/ getc, 
current working directory, 
getuid, geteuid, getgid, 
environment variable, 
environment name, 
real user, effective/ getuid, 
user,/ getuid, geteuid. 
setgrent, endgrent,/ 
endgrent,/ getgrent, 
getgrent, getgrgid, 

argument vector. 

process group, and/ getpid. 
process, process group, and/ 



functions and subroutines from/ 

functions 

functions, /lshift, rshift: . . 
functions, dim, ddim, idim: 
functions, /sqrt: exponential, 
functions, /floor, ceiling, . . 
functions, /maxl, amaxl, 
functions, /mini, aminl, 
functions, mod, amod, dmod: 
functions, /nint, idnint: . . 

functions 

functions, /lgt, lie, lit: . . . 
functions, /tan, asin, acos, . 
fwrite: binary input/output. 

gamma function 

gamma: log gamma function, 
gcvt: convert floating-point . 
generate an IOT fault. . . 
generate DES encryption, 
generate file name for ... 
generate uniformly distributed/ 

generator, rand, 

generator, irand, 

get a string from a stream. . 
get and set user limits. . . 
get character login name of 
get character or word from a/ 
get entries from name list. . 
get file creation mask. . . . 

get file status 

get file system statistics. . . 

get group file entry 

get login name 

get message queue 

get name from UID. . . . 
get name of current UNIX . 
get option letter from . . . 
get password file entry. . . 
get path-name of current 
get process and child process 
get process, process group, . 
get real user, effective user,/ 
get set of semaphores. . . . 
get shared memory segment. 

get time 

getarg: return Fortran . . . 
getc, getchar, fgetc, getw: 
getchar, fgetc, getw: get . . 
getcwd: get path-name of 
getegid: get real user,/ . . 
getenv: return Fortran . . . 
getenv: return value for . . 
geteuid, getgid, getegid: get 
getgid, getegid: get real . . 
getgrent, getgrgid, getgrnam, 
getgrgid, getgrnam, setgrent, 
getgrnam, setgrent, endgrent,/ 
getlogin: get login name. . . 
getopt: get option letter from 
getpass: read a password, 
getpgrp, getppid: get process, 
getpid, getpgrp, getppid: get 



mil(3F) 
bessel (3 M) 
bool(3F) 
dim(3F) 
exp(3M) 
floor(3M) 
max(3F) 
min(3F) 
mod(3F) 
round (3 F) 
sinh(3M) 
strcmp(3F) 
trigOk) 
fread (3S) 
gamma (3 M) 
gamma (3 M) 
ecvt(3C) 
abort (3C) 
crypt(3C) 
ctermid (3S) 
drand48(3C) 
rand(3C) 
rand (3 F) 
gets(3S) 
ulimit(2) 
cuserid (3S) 
getc(3S) 
nlist(3C) 
umask(2) 
stat (2) 
ustat (2) 
geterentOC) 
getloginQC) 
msgget (2) 
getpw (3C) 
uname (2) 
getopt (3C) 
getpwent(3C) 
getcwd (3C) 
times (2) 
getpid (2) 
getuid (?X 



time(2) 
getarg (3 F) 
getcGS) 
getc(3S) v 
getcwd (3C) 
getuid (2) 
getenv (3 F) 
getenv(3C) 



getgrent (3C) 
getgrent (3C) 
getgrent (3C) 
getlogin (3C) 
getopt(3C) 
getpass (3C) 
getpid (2) 
getpid(2) 
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group, and/ getpid, getpgrp, 

setpwent, endpwent,/ 
getpwent. getpwuid, 
endpwent,/ getpwent, 
a stream. 

and terminal settings used by 
settings used by getty. 
getegid: get real user,/ 
pututhne, setutent,/ 
setutent, endutent,/ getutent, 
setutent,/ getutent, getutid, 
from a/ getc, getchar, fgetc, 
convert/ ctime, localtime, 
setjmp, longjmp: non-local 
string, format or graphical/ 
primitive string, format of 
format of graphical/ gps: 
plot: 

subroutines, plot: 
/user, effective user, real 
/getppid: get process, process 
endgrent, fgetgrent: get 
group: 

setpgrp: set process 
real group, and effective 
setuid, setgia: set user and 
chown: change owner and 
a signal to a process or a 
ssignal, 
varargs: 

package, curses: CRT screen 
hcreate, hdestroy: manage 
search tables, hsearch., 
tables, hsearch, hcreate, 
file, scnhdr: section 
files, filehdr: file 
file, ldfhread: read the file 
/seek to the optional file 
/read an indexed/named section 
ldahread: read the archive 
manage hash search tables, 
cosh, dcosh: Fortran 
sinh, cosh, tanh: 
sinh, dsinh: Fortran 
tanh, dtanh: Fortran 
function. 

Fortran absolute value, abs, 
ishftc, ibits, btest,/ ior, 
command line arguments, 
/ishftc, ibits, btest, ibset, 
/not, ieor, ishft, ishftc, 
/ishft, ishftc, ibits, btest, 
/sngl, dole, cmplx, dcmplx, 
setpgrp: set process group 
issue: issue 
intrinsic/ dim, ddim, 
dble, cmplx,/ int, ifix, 
integer/ anint, dnint, nint, 
group, and parent process 
group, and effective group 



getppid: get process, process 
getpw: get name from UID. 
getpwent, getpwuid, getpwnam 
getpwnam, setpwent, endpwent 
getpwuid, getpwnam, setpwent 
gets, fgets: get a string from 
getty. gettydefs: speed . . . 
gettydefs: speed and terminal 
getuid, geteuid, getgid, 
getutent, getutidT getutline, 
getutid, getutline, pututline, 
getutline, pututline, . . . 
getw: get character or word 
gmtime, asctime, tzset: 

goto 

gps: graphical primitive 
graphical files, /graphical 
graphical primitive string, 
graphics interface. . . . 
graphics interface .... 
group, and effective group/ 
group, and parent process IDs 
group file entry, /setgrent, 

group file 

group: group file. ... 

group ID 

group IDs. /effective user, 

group IDs 

group of a file 

group of processes, /send 

f signal: software signals, 
andle variable argument list 
handling and optimization 
hash search tables, hsearch, 
hcreate, hdestroy: manage hash 
hdestroy: manage hash search 
header for a common object 
header for common object 
header of a common object 
header of a common object/ 
header of a common object/ 
header of a member of an/ 
hsearch, hcreate, hdestroy: 
hyperbolic cosine intrinsic/ 
hyperbolic functions. . . 
hyperbolic sine intrinsic/ . 
hyperbolic tangent intrinsic/ 
hypot: Euclidean distance 
iabs, dabs, cabs, zabs: . . 
iand, not, ieor, ishft, . . . 
iargc: return the number of 
ibclr, mvbits: bit field/ . . 
ibits, btest, ibset, ibclr,/ . 
ibset, ibclr, mvbits: bit/ 
ichar, char: explicit Fortran/ 
ID 



identification file. ... 
idim: positive difference 
idint, real, float, sngl, . 
idnint: Fortran nearest . 
IDs. /get process, process 
IDs. /effective user, real 



getpid(2) 
getpw (3C) 
getpwent (3 C) 
getpwent (3C) 
getpwent (3C) 
gets(3S) 
gettydefs (4) 
gettydefs (4) 
getuid (2) 
getut(3C) 
getutGC) 
getut(3C) 
getc(3S) 
ctime(3C) 
setjmp (3C) 
gps (4) 
gps (4) 
gps (4) 
pTot(4) 
plot(3X) 
getuid (2) 
getpid(2) 
getgrentOC) 
group (4) 
group (4) 
setpgrp (2) 
getuidt2) 
setuid (2) 
chown (2) 
kill (2) 
ssignal (3C) 
varargs (5) 
curses (3X) 
hsearch (3C) 
hsearch (3 C) 
hsearch (3 C) 
scnhdr (4) 
filehdr (4) 
ldfhread (3X) 
ldohseek(3X) 
ldshread(3X) 
ldahread (3X) 
hsearch (3C) 
cosh (3 F) 
sinh(3M) 
sinh(3F) 
tanh (3 F) 
hypot (3 M) 
abs(3F) 
mil(3F) 
iargc (3 F) 
mif(3F) 
mil(3F) 
mil(3F) 
ftype(3F) 
setpgrp(2) 
issue (4) 
dim(3F) 

round (3 F) 
getpid(2) 
getuid (2) 
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setgid: set user and group 
btest, ibset,/ ior, iand, not, 
sngl, dole, cmplx,/ int, 
core: format of core 
pnch: file format for card 
aimag, dimag: Fortran 
for formatting a permuted 
of a/ ldtbindex: compute the 
Fortran substring, 
a common/ ldtbread: read an 
ldshread, ldnshread: read an 
ldsseek, ldnsseek: seek to an 
inittab: script for the 
process, popen, pclose: 
process. 

inode: format of an 
sscanf: convert formatted 
push character back into 
fread, fwrite: binary 
stdio: standard buffered 
fileno: stream status 
sngl, dble, cmplx, dcmplx,/ 
abs: return 
/164a: convert between long 
sputl, sgetl: access long 
nint, ldnint: Fortran nearest 
function, aint, dint: Fortran 
atol, atoi: convert string to 
/ltol3: convert between 3 -byte 
3 -byte integers and long 
plot: graphics 
plot: graphics 
pipe: create an 
package, ftok: standard 
sleep: suspend execution for 
acos, dacos: Fortran arccosine 
dint: Fortran integer part 
asin, dasin: Fortran arcsine 
datan2: Fortran arctangent 
datan: Fortran arctangent 
Fortran complex conjugate 
dcos, ccos: Fortran cosine 
Fortran hyperbolic cosine 
double precision product 
cexp: Fortran exponential 
Fortran common logarithm 
Fortran natural logarithm 
Fortran transfer-of-sign 
sin, dsin, csin: Fortran sine 
dsinh: Fortran hyperbolic sine 
csqrt: Fortran square root 
tan, dtan: Fortran tangent 
Fortran hyperbolic tangent 
/mvbits: bit field manipulation 
idim: positive difference 
dmod: Fortran remaindering 
lie, lit: string comparison 
formats, 
miscellany, 
subroutines and libraries, 
calls and error numbers. 



IDs. setuid, setuid(2) 

eor, ishft, ishftc, ibits, mil(3F) 

fix, idint, real, float, ftype(3F) 

mage file core (4) 

mages pnch (4) 



maginary part of complex/ 
ndex. /the macro package . , 
ndex of a symbol table entry , 
ndex: return location of . . , 
ndexed symbol table entry of 
ndexed/named section header/ 
ndexed/named section of a/ 

nit process 

nitiate pipe to/from a . . 
nittab: script for the init 
node: format of an i-node. 
node. 

nput. scanf, fscanf, . . . 
nput stream, ungetc: . . 

nput/output 

nput/output package. . . 
nquiries. /feof, clearerr, . 
nt, ifix, idint, real, float, . 
nteger absolute value. . . 
nteger and base-64 ASCII/ 
nteger data in a/ .... 
nteger functions, /dnint, 
nteger part intrinsic . . 

nteger. strtol, 

ntegers and long integers, 
ntegers. /convert between 

nterface 

nterface subroutines. . . 
nterprocess channel. . . 
nterprocess communication 

nterval 

ntrinsic function 

ntrinsic function, 
ntrinsic function, 
ntrinsic function, 
ntrinsic function, 
ntrinsic function, 
ntrinsic function, 
ntrinsic function, 
ntrinsic function, dprod: 
ntrinsic function, /dexp, 
ntrinsic function. /dloglO: 
ntrinsic function, /clog: . 
ntrinsic function, /dsign: 

ntrinsic function 

ntrinsic function, sinh, 
ntrinsic function, /dsqrt, 

ntrinsic function 

ntrinsic function, /dtanh: 
ntrinsic functions and/ 
ntrinsic functions, /ddim, 
ntrinsic functions, /amod, 
ntrinsic functions, /let, . 
ntro: introduction to file . 
ntro: introduction to . . 
ntro: introduction to . . 
ntro: introduction to system 



aint, 



atan2, . 
atan, . 
/dconjg: 
cos, . . 
/dcosh: 



aima g(3F) 
mptxT5) 
ldtbindex (3X) 
index (3 F) 
ldtbread (3X) 
ldshread (3X) 
ldsseek(3X) 
inittab(4) 
popen (3S) 
inittab (4) 
inode (4) 
inode(4) 
scanfuS) 
ungetc (3S) 
fread (3S) 
stdio (3S) 
ferror(3S) 
ftype(3F) 
abs(3C) 
a641(3C) 
sputl (3X) 
round (3 F) 
aint (3 F) 
strtol (30 
13tol(3C) 
13tol(3C) 
plot (4) 
plot(3X) 
pipe (2) 
stdipc(3C) 
sleep (30 
acos (3 F) 
aint (3 F) 
asin(3F) 
atan2(3F) 
atan (3 F) 
conig(3F) 
cos(3F) 
cosh (3 F) 
dprod (3 F) 
exp(3F) 
log 10 (3 F) 

sign (3 F) 

sin(3F) 

sinh (3 F) 

sqrt(3F) 

tan(3F) 

tanh(3F) 

mil(3F) 

dim(3F) 

mod(3F) 

strcmp(3F) 

intro(4) 

intro(5) 

intro(3) 

intro(2) 
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intro: 
intro: 

and libraries, intro: 
and error numbers, intro: 

ishftc, ibits, btest, ibset,/ 
abort: generate an 
number generator, 
/islower, isdigit, isxdigit. 
isdigitj isxdigit, isalnum,/ 
/isprint, isgraph, iscntrl, 
terminal, ttyname, 
/ispunct, isprint, isgraph, 
isalpha, isupper, islower, 
/isspace, ispunct, isprint, 
ibset,/ ior, iand, not, ieor, 
ior, iand, not, ieor, ishft, 
transfer -of-sign/ sign, 
isalnum,/ isalpha, isupper, 
/isalnum, isspace, ispunct, 
/isxdigit, isalnum, isspace, 
/isdigit, isxdigit, isalnum, 
Fortran, system: 
system: 
issue: 
file. 

isxdigit, isalnum,/ isalpha, 
/isupper, islower, isdigit, 
functions, 
functions. jO, 
functions. jO, jl , 
/lrand48, nrand48, mrand48. 
process or a group of/ 
3 -byte integers and long/ 
integer and base-64/ a641, 
troff: description of output 
/jrand48, srand48, see< f48, 
object file, ldclose. 
header of a member of an/ 
file for reading, ldopen, 
common object file, 
of floating-point/ frexp, 
access routines, 
of a common object file, 
name for common object file/ 
line number entries/ ldlread, 
number/ ldlread, ldlinit. 
manipulate line number/ 
line number entries of a/ 
entries of a section/ ldlseek, 
entries of a section/ ldrseek, 
indexed/named/ ldshread, 
indexed/named/ ldsseek. 
file header of a common/ 
object file for reading, 
relocation entries of a/ 
indexed/named section header/ 
indexed/named section of a/ 
of a symbol table entry of a/ 
symbol table entry of a/ 
table of a common object/ 
string. 



introduction to file formats, 
introduction to miscellany, 
introduction to subroutines 
introduction to system calls 
ioctl: control device. . . . 
ior, iand, not, ieor, ishft, . 

IOT fault 

irand, rand, srand: random 
isalnum, isspace, ispunct,/ 
isalpha, isupper, islower, . 
isascii: classify characters, 
isatty: find name of a 
iscntrl, isascii: classify/ 
isdigit, isxdigit, isalnum,/ 
isgraph, iscntrl, isascii:/ . 
ishft, ishftc, ibits, btest, 
ishftc, ibits, btest, ibset,/ . 
isign, dsign: Fortran . . . 
islower, isdigit, isxdigit, 
isprint, isgraph, iscntrl,/ . 
ispunct, isprint, isgraph,/ 
isspace, ispunct, isprint,/ . 
issue a shell command from 
issue a shell command, 
issue identification file, 
issue: issue identification . 
isupper, islower, isdigit, 
isxdigit, isalnum, isspace,/ 
jO, jl, jn, yO, yl, yn: Bessel 
j 1 , jn, yO, yl, yn: Bessel . 
jn, yO, yl, yn: Bessel . . 
irand48, srand48, seed48,/ 
kill: send a signal to a . . 
13tol, ltol3: convert between 
164a: convert between long 

language 

lcong48: generate uniformly/ 
ldaciose: close a common 
ldahread: read the archive 
ldaopen: open a common object 
ldclose, ldaciose: close a . . 
ldexp, modf: manipulate parts 
ldfcn: common object file 
ldfhread: read the file header 
ldgetname: retrieve symbol 
ldlinit, ldlitem: manipulate 
ldlitem: manipulate fine . 
ldlread, ldlinit, ldlitem: 
ldlseek, ldnlseek: seek to . 
ldnlseek: seek to line number 
ldnrseek: seek to relocation 
ldnshread: read an ... 
ldnsseek: seek to an . . . 
ldohseek: seek to the optional 
ldopen, ldaopen: open a common 
ldrseek, ldnrseek: seek to . . 
ldshread, ldnshread: read an 
ldsseek, ldnsseek: seek to an 
ldtbindex: compute the index 
ldtbread: read an indexed 
ldtbseek: seek to the symbol 
len: return length of Fortran 



intro (4) 
intro (5) 
intro (3) 
intro (2) 
ioctl (2) 
mil(3F) 
abort (3C) 
rand(3F) 
ctype(3C) 
ctypeGC) 
ctypeuO 
ttyname (3C) 
ctype(3C) 
ctypeGC) 
ctypeuO 
miR3F) 
mil(3F) 
sign (3 F) 
ctype(3C) 
ctypeGC) 
ctype(3C) 
ctypeUC) 
system (3 F) 
system (3S) 
issue (4) 
issue (4) 
ctype(3C) 
ctype(3C) 
bessel (3 M) 
bessel ( 3 M) 
bessel (3 M) 
drand48(3C) 
kill (2) 
13tol(3C) 
a641(3C) 
troff(5) 
drand48(3C) 
ldclose (3X) 
ldahread (3X) 
ldopen (3X) 
ldclose (3X) 
frexp(3C) 
ldfcn(4) 
ldfhread (3X) 
ldgetname (3X) 
ldlread (3X) 
ldlread (3X) 
ldlread (3X) 
ldlseek(3X) 
ldlseek (3X) 
ldrseek(3X) 
ldshread (3X) 
ldsseek(3X) 
ldohseek(3X) 
ldopen (3X) 
ldrseek (3X) 
ldshread (3X) 
ldsseek(3X) 
ldtbindex(3X) 
ldtbread (3X) 
ldtbseek(3X) 
len(3F) 
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len: return 
getopt: get option 
update, lsearch, 
comparison intrinsic/ 
comparison intrinsic/ lge, 
to subroutines and 
ulimit: get and set user 
return the number of command 
an out-going terminal 
common object file, linenum: 
/ldlinit, ldlitem: manipulate 
ldlseek, ldnlseek: seek to 
lsearch, lfind: 
in a common object file, 
a.out: common assembler and 

link: 

nlist: get entries from name 
by fsck. checklist: 
handle variable argument 
output of a varargs argument 
output of a varargs argument 
intrinsic/ Ige, let, 
intrinsic/ lge, lgt, lie, 
tzset: convert date/ ctime, 
index: return 
end, etext, edata: last 
memory, plock: 
files, 
lockf: record 
natural logarithm intrinsic/ 
gamma: 

exponential, logarithm,/ exp. 
common logarithm intrinsic/ 
logarithm, power,/ exp, log, 
/aloglO, dlog 10: Fortran common 
/dlog, clog: Fortran natural 
/log 10, pow, sqrt: exponential, 
getlogin: get 
cuserid: get character 
logname: return 
setting up an environment at 
user. 

a641, 164a: convert between 
sputl, sgetl: access 
between 3 -byte integers and 
setjmp, 

jrand48,/ drand48, erand48, 
and update, 
pointer. 

Bitwise/ and, or, xor, not, 
integers and long/ 13tol, 
values: 

/access long integer data in a 
permuted index, mptx: the 
documents, mm: the MM 
mosd: the OSDD adapter 
viewgraphs and/ mv: a troff 
in this manual, man: 
malloc, free, realloc, calloc: 
/mallopt, mallinfo: fast 
or ordinary file, mknod: 



ength of Fortran string. . . 
etter from argument vector, 
find: linear search and . . 
ge, let, He, lit: string . . . 

, lie, lit: string 

raries. /introduction . . 

imits. ... . 

ine arguments, iargc: . . . 
ine connection, /establish . 
ine number entries in a . . 
ine number entries of a/ 
ine number entries of a/ 
inear search and update, 
inenum: line number entries 

ink editor output 

ink: link to a file 

ink to a file 

ist 



ist of file systems processed . , 

ist. varargs: 

ist. /print formatted 

ist. /print formatted 

le, lit: string comparison . . . , 

It: string comparison 

ocaltime, gmtime, asctime, . . 
ocation of Fortran substring. . . 

ocations in program 

ock process, text, or data in . , 
ockf: record locking on . . . , 

ocking on files 

og, alog, dlog, clog: Fortran . , 

og gamma function 

og,logl0, pow, sqrt: 

og 10, alog 10, dlog 10: Fortran 
oglO, pow, sqrt: exponential, . , 
ogarithm intrinsic function. . . 
ogarithm intrinsic function. . . 
ogarithm, power, square root/ 

ogin name 

ogin name of the user 

ogin name of user 

ogin time, profile: 

ogname: return login name of 
ong integer and base-64 ASCII/ 
ong integer data in a/ . . . 
ong integers. /ltol3: convert 
ongjmp: non-local goto. . . 
rand48, nrand48, mrand48, 
search, lfind: linear search . 
seek: move read/write file . 
shift, rshift: Fortran . . . 
to!3: convert between 3 -byte 
machine-dependent values. . 
machine-independent fashion., 
macro package for formatting a 
macro package for formatting 
macro package for formatting/ 
macro package for typesetting 
macros for formatting entries . 
main memory allocator. . . . 
main memory allocator. . . . 
make a directory, or a special 



len(3F) 
getopt (3C) 
lsearch (3C) 
strcmp(3F) 
strcmp(3F) 
intro(3) 
ulimit (2) 
iargc (3 F) 
dia?(3C) 
linenum (4) 
ldlread(3X) 
ldlseek(3X) 
lsearch (30 
linenum (4) 
a.out (4) 
link(2) 
link(2) 
nlist(3C) 
checklist (4) 
varargs (5) 
vprintf(3S) 
vprintfGX) 
strcmp(3F^ 
strcmp(3F 
ctimeUC) 
index (3 F) 
end(3C) 
plock (2) 
fockf(3C) 
lockf(3C) 
log(3F) 
gamma (3 M) 
exp(3M) 
log 10 (3 F) 
exp(3M) 
logl0(3F) 
log(3F) 
exp(3M) 
getlogin (3C) 
cuserid (3S) 
logname (3X) 
profile (4) 
logname (3X) 
a641(3C) 
sputl (3X) 
13tol(3C) 
setjmp (3C) 
drand48(3C) 
IsearchOC) 
lseek(2) 
bool(3F) 
13tol(3C) 
values (5) 
sputl (3X) 
mptx (5) 
mm(5) 
mosd (5) 
mv(5) 
man (5) 
malloc (3C) 
malloc (3X) 
mknod (2) 
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mktemp: make a unique file name. . . . mktemp(3C) 

/realloc, calloc, mallopt, mallinfo: fast main memory/ . . malloc (3X) 

main memory allocator, malloc, free, realloc, calloc: . . malloc(3C) 

mallopt, mallinfo: fast main/ malloc, free, realloc, calloc, . . malloc (3X) 

malloc, free, realloc, calloc, mallopt, mallinfo: fast main/ . . malloc (3X) 

entries in this manual, man: macros for formatting . . man (5) 

/tfind, tdelete, twalk: manage binary search trees. . . tsearch(3C) 

hsearch, hcreate, hdestroy: manage hash search tables. . . . hsearch(3C) 

of/ ldlread, ldlinit, ldlitem: manipulate line number entries . ldlread(3X) 

frexp, ldexp, modf: manipulate parts of/ frexp(3C) 

ibclr, mvbits: bit field manipulation intrinsic/ /ibset, . milC3F) 

for formatting entries in this manual, man: macros man (5) 

ascii: map of ASCII character set. . . ascii(5) 

set and get file creation mask, umask: umask(2) 

table, master: master device information . . . master (4) 

information table, master: master device master (4) 

regular expression compile and match routines, regexp: .... regexp(5) 

math: math functions and constants. . math (5) 

constants, math: math functions and . . . math (5) 

function, matherr: error-handling .... matherr(3M) 

dmaxl: Fortran maximum-value/ max, maxO, amaxO, maxl, amaxl, max(3F) 

dmaxl: Fortran/ max, maxO, amaxO, maxl, amaxl, . . max(3F) 

max, maxO, amaxO, maxl, amaxl, dmaxl: Fortran/ . max(3F) 

/maxl, amaxl, dmaxl: Fortran maximum-value functions. . . . max(3F) 

accounting, mclock: return Fortran time . . mclock(3F) 

memcpy, memset: memory/ memccpy, memchr, memcmp, . memory (3C) 

memset: memory/ memccpy, memchr, memcmp, memcpy, . . memory (3C) 

operations, memccpy, memchr, memcmp, memcpy, memset: memory memory (3C) 

memccpy, memchr, memcmp, memcpy, memset: memory/ . . memory(3C) 

free, realloc, calloc: main memory allocator, malloc, . . . malloc(3C) 

mallopt, mallinfo: fast main memory allocator, /calloc, . . . malloc (3X) 

shmctl: shared memory control operations. . . . shmctlu) 

memcmp, memcpy, memset: memory operations, /memchr, . memory (3 C) 

shmop: shared memory operations shmopu) 

lock process, text, or data in memory, plock: plocku) 

shmget: get shared memory segment shmget(2) 

/memchr, memcmp, memcpy, memset: memory operations. . . memory (3C) 

msgctl: message control operations. . . . msgctlu) 

msgop: message operations msgop(2) 

msgget: get message queue msgget(2) 

sys nerr: system error messages, /errno, sys errlist, . . perror(3C) 

subroutines from the Fortran Military Standard/ /and . . . mil(3F) 

the Fortran Military Standard (MIL-STD-1753).. /from . . . mil(3F) 

dminl: Fortran minimum-value/ min, minO, aminO, mini, aminl, min(3F) 

dminl: Fortran/ min, minO, aminO, mini, aminl, . . . min(3F) 

min, minO, aminO, mini, aminl, dminl: Fortran/ . min(3F) 

/mini, aminl, dminl: Fortran minimum-value functions. . . . min(3F) 

special or ordinary file, mknod: make a directory, or a . mknod(2) 

name, mktemp: make a unique file . . mktemp (3C) 

formatting documents, mm: the MM macro package for .... mm(5) 

formatting documents, mm: the MM macro package for mm (5) 

table, mnttab: mounted file system . . mnttab (4) 

remaindering intrinsic/ mod, amod, dmod: Fortran . . . mod(3F) 

chmod: change mode of file chmod(2) 

floating-point/ frexp, ldexp modf: manipulate parts of ... frexp(3C) 

utime: set file access and modification times utime(2) 

profile, monitor: prepare execution . . . monitor (3C) 

package for formatting/ mosd: the OSDD adapter macro mosd(5) 

mount: mount a file system mount(2) 

mount: mount a file system. . . mount (2) 

mnttab: mounted file system table. . . . mnttab (4) 

lseek: move read/ write file pointer. . . lseek(2) 
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formatting a permuted index. 
/erand48, lrand48, nrand48, 
operations. 



typesetting viewgraphs and/ 
/ibits, btest, ibset, ibclr, 
log, alog, dlog, clog: Fortran 
/dnint, nint, idnint: Fortran 
definitions for eqn and 
process, 
integer/ anint, dnint, 
list. 

setjmp, longjmp: 
ibits, btest,/ ior, land, 
Bitwise Boolean/ and, or, xor, 
drand48, erand48, lrand48, 
ldfcn: common 
ldopen, ldaopen: open a common 
number entries of a common 
ldaclose: close a common 
the file header of a common 
of a section of a common 
file header of a common 
of a section of a common 
section header of a common 
section of a common 
symbol table entry of a common 
symbol table entry of a common 
the symbol table of a common 
number entries in a common 
information for a common 
section header for a common 
entry, /symbol name for common 
format, syms: common 
file header for common 
reading, ldopen, ldaopen: 
fopen, freopen, fdopen: 
dup: duplicate an 
open: 
writing. 

memcmp, memcpy, memset: memory 
msgctl: message control 
msgop: message 
semctl: semaphore control 
semop: semaphore 
shmctl: shared memory control 
shmop: shared memory 
strcspn, strtok: string 
CRT screen handling and 
vector, getopt: get 
common/ ldohseek: seek to the 
fcntl: file control 
Fortran Bitwise Boolean/ and, 
a directory, or a special or 
formatting/ mosd: the 
dial: establish an 
assembler and link editor 
troff: description of 
/vsprintf: print formatted 
/vsprintf: print formatted 
sprintf: print formatted 



mptx: the macro package for 
mrand48, jrand48, srand48,/ 
msgctl: message control . . 
msgget: get message queue, 
msgop: message operations, 
mv: a troff macro package for 
mvbits: bit field manipulation/ 
natural logarithm intrinsic/ . . 
nearest integer functions. . . . 
neqn. /special character .... 
nice: change priority of a ... 
nint, idnint: Fortran nearest 
nlist: get entries from name . . 

non-local goto 

not, ieor. ishftj ishftc, 

not, lshift, rshift: Fortran . . . 
nrand48. mrand48, jrand48,/ . . 
object file access routines. . . . 

object file for reading 

object file function, /line ... 
object file, ldclose, . . * . . . 
object file, ldfhread: read . . . 
object file, /number entries . . 
object file, /to the optional . . . 

object file, /entries 

object file, /indexed/named . . 
object file, /indexed/named . . 
object file, /the index of a ... 
object file, /read an indexed . . 

object file, /seek to 

object file, linenum: line .... 

object file, /relocation 

object file, scnhdr: 

object file symbol table .... 
object file symbol table .... 

object files, filehdr: 

open a common object file for 

open a stream 

open file descriptor. ...... 

open for reading or writing. . . 
open: open for reading or ... 
operations, memccpy, memchr, . 

operations 

operations 

operations 

operations 

operations 

operations. 

operations, /strpbrk, strspn, . . 
optimization package, curses: . . 
option letter from argument . . 
optional file header of a .... 

options. . 

or, xor, not, lshift, rshift: .... 
ordinary file, mknod: make . . 
OSDD adapter macro package for 
out-going terminal line/ .... 
output, a. out: common .... 

output language 

output of a varargs argument/ 
output of a varargs argument/ 
output, printf , fprintf, 



mptx (5) 

drand48(3C) 

msgctl (2) 

msgget (2) 

msgop(2) 

mv°5) 

mil(3F) 

log(3F) v 

round (3F) 

eqnchar(5) 

nice (2) 

round (3 F) 

nlist (3C) 

setjmp(3C) 

miI(3F) 

bool(3F) 

drand48(3C) 

ldfcn(4) 

ldopen (3X) 

ldlread(3X) 

ldclose(3X) 

ldfhread (3X) 

ldlseek(3X) 

ldohseek(3X) 

ldrseek(3X) 

ldshread(3X) 

ldsseek(3X) 

ldtbindex(3X) 

ldtbread(3X) 

ldtbseek(3X) 

linenum (4) 

reloc(4) 

scnhdr (4) 

ldgetname(3X) 

syms (4) 

filehdr (4) 

ldopen (3X) 

fopen(3S) 

dup(2) 

open (2) 

open (2) 

memory OC) 

msgctl (2) 



semop (2) 
shmctl (2) 
shmop (2) 
string (30 
curses (3X) 
getopt (3 C) 
Fdohseek(3X) 
fcntl (5) 
bool(3F) 
mknod (2) 
mosd (5) 
dial(3C) 
a.out(4) 
troff(5) 
vprintf(3S) 
vprintf(3X) 
printf(3S) 
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chown: change 
handling and optimization 
permuted/ mptx: the macro 
documents, mm: the MM macro 
mosd: the OSDD adapter macro 
viewgraphs/ mv: a troff macro 
standard buffered input/output 
interprocess communication 
process, process group, and 

/endpwent, fgetpwent: get 
putpwent: write 
passwd: 
getpass: read a 
directory, getcwd: get 
signal, 
a process, popen, 
macro package for formatting a 
format, acct: 
sysnerr: system error/ 
channel, 
popen. pclose: initiate 
data in memory. 

subroutines, 
images, 
ftell: reposition a file 
lseek: move read/write file 
to/from a process, 
functions, dim, ddim, idim: 
logarithm,/ exp, log, log 10, 
/sqrt: exponential, logarithm, 
function. dprocH double 
monitor: 

graphical/ gps: graphical 
types: 

vprintf, vfprintf, vspnntf: 
vprintf, vfprintf, vsprintf: 
printf, f printf, sprintf: 
print formatted output. 

nice: change 
acct: enable or disable 
alarm: set a 
times, times: get 
exit, exit: terminate 
fork: create a new 
/getpgrp, getppid: get process, 
setpgrp: set 
process group, andparent 
inittab: script for trie init 
nice: change priority of a 
kill: send a signal to a 
initiate pipe to/from a 
getpid, getpgrp, getppid: get 
memory, plock: lock 
times: get process and child 
wait: wait for child 
ptrace: 
pause: suspend 
list of file systems 
to a process or a group of 
dprod: double precision 



owner and group of a file, 
package, curses: CRT screen 
package for formatting a 
package for formatting 
package for formatting/ 
package for typesetting 
package, stdio: .... 
package, ftok: standard 
parent process IDs. /get 
passwd: password file. . 
password file entry. . . 
password file entry. . . 
password file. .... 

password 

path-name of current working 
pause: suspend process until 
pclose: initiate pipe to/from 
permuted index, mptx: the 
per-process accounting file 
perror, errno, sys errhst, . 
pipe: create an interprocess 
pipe to/from a process, 
plock: lock process, text, or 
plot: graphics interface, 
plot: graphics interface 
pnch: file format for card 
pointer in a stream, /rewind, 

pointer 

popen, pclose: initiate pipe 
positive difference intrinsic 
pow, sqrt: exponential, . . 
power, square root functions, 
precision product intrinsic 
prepare execution profile, 
primitive string, format of 
primitive system data types, 
print formatted output of a/ 
print formatted output of a/ 
print formatted output, 
printf, fprintf, sprintf: . . 
priority of a process. . . 
process accounting. . . . 
process alarm clock. . . . 
process and child process 

process 

process 

process group, and parent/ 

process group ID 

process IDs. /get process, 

process 

process 

process or a group of/ . . 
process, popen, pclose: . . 
process, process group, and/ 
process, text, or data in 

process times 

process to stop or terminate. 

process trace 

process until signal. . . . 
processed by fsck. checklist: 
processes, /send a signal . 
product intrinsic function. 



chown (2) 
curses (3X) 
mptx (5) 
mm (5) 
mosd (5) 
mv(5) 
stdioOS) 
stdipc(3C) 
getpid(2) 
passwd (4) 
getpwent(3C) 
putpwent (3C) 
passwd (4) 
getpass (30 
getcwd (30 
pause (2) 
popenUS) 
mptx (5) 
acct (4) 
perror (30 
pipe (2) 
popen (3S) 
plock(2) 
plot (4) 
plot(3X) 

finch (4) 
seek(3S) 
lseek (2) 
popen (3S) 
dim(3F) 
exp(3M) 
exp(3M) 
dprod (3 F) 
monitor (30 
gps (4) 
types(5) 
vprintf(3S) 
vprintf(3X) 
printf(3S) 
printf(3S) 
nice (2) 
acct (2) 
alarm (2) 
times(2) 
exit (2) 
fork(2) 
getpid (2) 

inittab (4) 
nice (2) 
kill (2) 
popen (3S) 
getpid(2) 
plock(2) 
times (2) 
wait (2) 
ptrace (2) 
pause (2) 
checklist (4) 
kill (2) 
dprod (3F) 
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function, 
profile. 

monitor: prepare execution 
profil: execution time 
environment at login time. 

prof: 

/generate uniformly distributed 

stream, ungetc: 
put character or word on a/ 
character or word on a/ putc, 
environment, 
entry, 
stream. 

getutent, getutid, getutline, 
a/ putc, putchar, fputc, 

msgget: get message 
qsort: 

generator, irand, 
random-number generator, 
irand, rand, srand: 
rand, srand: simple 
getpass: 

entry of a common/ ldtbread: 
header/ ldshread, ldnshread: 
read: 

member of an/ ldahread: 
common object file, ldfhread: 
open a common object file for 
open: open for 
lseek: move 
cmplx,/ int, ifix, idint, 
allocator, malloc, free, 
mallinfo: fast/ malloc, free, 
specify what to do upon 
/specify Fortran action on 
lockf: 

execute regular expression, 
regular expression, regcmp, 
compile and match routines, 
match routines, regexp: 
regex: compile and execute 
for a common object file, 
ldrseek, ldnrseek: seek to 
common object file, reloc: 
/fmod, fabs: floor, ceiling, 
mod, amod, dmod: Fortran 
unlink: 
clock: 

stream, fseek, rewind, ftell: 
common object file/ ldgetname: 
argument, getarg: 
variable, getenv: 
accounting, mclock: 
abs: 
string, len: 
substring, index: 
logname: 
line arguments, iargc: 
name, getenv: 



prof: profile within a ... 
profil: execution time . . . 

profile 

profile 

profile: setting up an ... 
profile within a function. . . 
pseudo-random numbers, 
ptrace: process trace. . . . 
push character back into input 
putc, putchar, fputc, putw: . 
putchar, fputc, putw: put 
putenv: change or add value to 
putpwent: write password file 
puts, fputs: put a string on a 
pututhne, setutent, endutent,/ 
putw: put character or word on 

qsort: quicker sort 

queue 

quicker sort 

rand, srand: random number 
rand, srand: simple .... 
random number generator. . 
random-number generator. . 

read a password 

read an indexed symbol table 
read an indexed/named section 

read from file 

read: read from file 

read the archive header of a 
read the file header of a . . 
reading, ldopen, ldaopen: 

reading or writing 

read/write file pointer. . . . 
real, float, sngl, dble, . . . 
realloc, calloc: main memory 
realloc, calloc, mallopt, . . 
receipt of a signal, signal: 
receipt of a system signal, 
record locking on files. . . . 
regcmp, regex: compile and 
regex: compile and execute . 
regexp: regular expression 
regular expression compile and 
regular expression, regcmp, 
reloc: relocation information 
relocation entries of a/ 
relocation information for a 
remainder, absolute value/ . 
remaindering intrinsic/ . . 
remove directory entry. . . 
report CPU time used. . . 
reposition a file pointer in a 
retrieve symbol name for . . 
return Fortran command-line 
return Fortran environment 
return Fortran time . . . 
return integer absolute value 
return length of Fortran . 
return location of Fortran 
return login name of user, 
return the number of command 
return value for environment . 



prof(5) 
profil (2) 
monitor (3C) 
profil (2) 
profile (4) 
prof(5) 
drand48(3C) 
ptrace (2) 
ungetc (3S) 
putc(3S) 
putc(3S) 
putenv (3C) 
putpwent (3C) 
puts(3S) 
getut(3C) 
putc(3S) 
qsort (3C) 
msgget (2) 
qsort (3C) 
rand (3 F) 
rand(3C) 
rand (3 F) 
rand(3C) 
getpassuC) 
ldtbread (3X) 
ldshread(3X) 
read (2) 
read (2) 
ldahread (3X) 
ldfhread (3X) 
ldopen (3X) 
open (2) 
lseek (2) 
ftype(3F) 
malloc (3C) 
malloc(3X) 
signal (2) 
signal (3 F) 
lockf(3C) 
regcmp (3X) 
regcmp (3X) 
regexp (5) 
regexp (5) 
regcmp (3X) 
reloc (4) 
ldrseek(3X) 
reloc (4) 
floor(3M) 
mod(3F) 
unlink (2) 
clock (3C) 
fseek (3S) 
ldgetname (3X) 
getarg(3F) 
getenv (3 F) 
mclock (3 F) 
abs(3C) 
len(3F) 
index (3 F) 
logname (3X) 
iargc (3 F) 
getenv (3 C) 



xxx-System Calls and Library Routines 



UNIX Programmer's Manual 



stat: data 
file pointer in a/ fseek, 
creat: create a new file or 
chroot: change 
logarithm, power, square 
/dsqrt, csqrt: Fortran square 
common object file access 
expression compile and match 
and, or, xor, not, lshift, 
space allocation, brk, 
formatted input, 
sccsfile: format of 

common object file, 
optimization/ curses: CRT 
inittab: 
bsearch: binary 
lsearch, lfind: linear 
hcreate, hdestroy: manage hash 
tdelete, twalk: manage binary 
object file, scnhdr: 
object/ /read an indexed/named 
/to line number entries of a 
/to relocation entries of a 
/seek to an indexed/named 
/mrand48. jrand48, srand48, 
section of/ ldsseek, ldnsseek: 
a section/ ldlseek, ldnlseek: 
a section/ ldrseek, ldnrseek: 
header of a common/ ldohseek: 
common object file, ldtbseek: 
shmget: get shared memory 
brk, sbrk: change data 
semctl: 
semop: 
semget: get set of 
operations. 



a group of processes, kill: 
buffering to a stream. 

IDs. setuid, 
getgrent, getgrgid, getgrnam, 
goto. 

encryption, crypt, 

getpwent, getpwuid, getpwnam, 
login time, profile: 
gettydefs: speed and terminal 
group IDs. 
/getutid, getutline, pututline, 
stream, setbuf, 
data in a/ sputl, 
operations, shmctl: 
shmop: 
shmget: get 
system: issue a 
system: issue a 
operations. 

segment, 
operations, 
transfer-of-sign intrinsic/ 



returned by stat system call, 
rewind, ftell: reposition a 
rewrite an existing one. . . 

root directory 

root functions, /exponential, 
root intrinsic function. . . . 

routines, ldfcn: 

routines, regexp: regular . . 
rshift: Fortran Bitwise/ . . 
sbrk: change data segment . 
scanf, fscanf, sscanf: convert 

SCCS file 

sccsfile: format of SCCS file, 
scnhdr: section header for a 
screen handling and .... 
script for the init process, 
search a sorted table. . . . 

search and update 

search tables, hsearch, . . 
search trees, tsearch, tfind, . 
section header for a common 
section header of a common 
section of a common object/ 
section of a common object/ 
section of a common object/ 
seed48, lcong48: generate/ . 
seek to an indexed/named 
seek to line number entries of 
seek to relocation entries of 
seek to the optional file . . 
seek to the symbol table of a 

segment 

segment space allocation, 
semaphore control operations, 
semaphore operations. . . . 

semaphores 

semctl: semaphore control 
semget: get set of semaphores, 
semop: semaphore operations, 
send a signal to a process or 
setbuf, setvbuf: assign . . . 
setgid: set user and group 
setgrent, endgrent, fgetgrent:/ 
setimp, longjmp: non-local . 
setkey, encrypt: generate DES 
setpgrp: set process group ID. 
setpwent, endpwent, fgetpwent 
setting up an environment at 
settings used by getty. . . . 
setuidj setgid: set user and . 
setutent, endutent, utmpname:/ 
setvbuf: assign buffering to a 
sgetl: access long integer . . 
snared memory control . . 
shared memory operations. . 
shared memory segment. . . 
shell command from Fortran. 

shell command 

shmctl: shared memory control 
shmget: get shared memory 
shmop: snared memory . . 
sign, isign, dsign: Fortran 



stat (5) 
fseekGS) 
creat (2) 
chroot (2) 
exp(3M) 
sqrt(3F) 
ldfcn (4) 
regexp (5) 
boolOF) 
brk(2) 
scanf(3S) 
sccsfile (4) 
sccsfile (4) 
scnhdr (4) 
curses ( 3 X) 
inittab (4) 
bsearch (3 C) 
lsearch (3C) 
hsearch (3 C) 
tsearch (3C) 
scnhdr (4) 
ldshread(3X) 
ldlseek(3X) 
ldrseekGX) 
ldsseek(3X) 
drand48(3C) 
ldsseek(3X) 
ldlseek(3X) 
ldrseek(3X) 
ldohseek(3X) 
ldtbseek(3X) 
shmget (2) 
brkQ) 
semctl (2) 
semop (2) 
semget (2) 
semctl (2) 
semget (2) 
semop (2) 
kill (2) 
setbuf(3S) 
setuid (2) 
getgrent (3C) 
setjmp(3C) 
crypt(3C) 
setpgrp (2) 
getpwent (3 C) 
profile (4) 
gettydefs (4) 
setuid (2) 
getut(3C) 
setbuf(3S) 
sputl(3X) 
shmctl (2) 
shmop (2) 
shmget (2) 
system (3 F) 
system (3S) 
shmctl (2) 
shmget (2) 
shmop(2) 
sign (3 F) 
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pause: suspend process until 
what to do upon receipt of a 
action on receipt of a system 
on receipt of a system/ 
upon receipt of a signal, 
or processes, kill: send a 
ssignal, gsignal: software 
generator, rand, srand: 
atan, atan2: trigonometric/ 
intrinsic function, 
sin, dsin, csin: Fortran 
/dsinh: Fortran hyperbolic 
functions, 
hyperbolic sine intrinsic/ 
interval. 

for typesetting viewgraphs and 
current/ ttyslot: find the 
int, ifix, idint, real, float, 
ssignal, gsignal: 
qsort: quicker 
bsearch: binary search a 
brk, sbrk: change data segment 
fspec: format 
receipt of a system/ signal: 
receipt of a signal, signal: 
used by getty. gettydefs: 
output, print?, fprintf. 
integer data in a/ 
square root intrinsic/ 
power,/ exp, log, log 10, pow, 
exponential, logarithm,power, 
sqrt, dsqrt, csqrt: Fortran 
generator, irand, rand, 
generator, rand, 
/nrand48, mrand48, irand48, 
input, scant, fscanf, 
signals, 
package, stdio: 
communication package, ftok: 
/from the Fortran Military 
system call. 

stat: data returned by 
ustat: get file system 
feof, clearerr, fileno: stream 
stat, fstat: get file 
input/output package. 

wait for child process to 
strncmp, strcpy, strncpy,/ 
/strcpy ? strncpy, strlen, 
strncpy,/ strcat, strncat, 
/strncat, strcmp, strncmp, 
/strrchr, strpbrk, strspn, 
fflush: close or flush a 
fopen, freopen, fdopen: open a 
reposition a file pointer in a 
get character or word from a 
fgets: get a string from a 
put character or word on a 
puts, fputs: put a string on a 
setvbuf: assign buffering to a 



signal pause (2) 

signal, signal: specify signal (2) 

signal, /specify Fortran .... signal (3 F) 
signal: specify Fortran action . . signal (3 F) 
signal: specify what to do ... signal (2) 
signal to a process or a group . . kill (2) 

signals ssignal (3 C) 

simple random-number .... rand(3C) 
sin, cos, tan, asin, acos, .... trig (3 M) 
sin, dsin, csin: Fortran sine . . . sint3F) 

sine intrinsic function sin( 3F) 

sine intrinsic function sinh (3 F) 

sinh, cosh, tanh: hyperbolic . . . sinh (3 M) 
sinh, dsinh: Fortran ...... sinh (3 F) 

sleep: suspend execution for . . sleep (3 C) 
slides, /a troff macro package . mvC5) 
slot in the utmp file of the ... ttyslot (3C) 
sngl, dble, cmplx, dcmplx,/ . . . ftype(3F) 

software signals ssignal (3 C) 

sort qsort (3C) 

sorted table bsearch (3 C) 

space allocation brk (2) 

specification in text files fspec (4) 

specify Fortran action on ... signal (3 F) 
specify what to do upon .... signal (2) 
speed and terminal settings . . . gettydefs (4) 
sprintf: print formatted .... printf(3S) 
sputl, sgetl: access long .... sputl(3X) 
sqrt, dsqrt, csqrt: Fortran . . . sqrt(3F) 
sqrt: exponential, logarithm, . . exp(3M) 
square root functions, /sqrt: . . exp(3M) 

square root intrinsic/ sqrt (3 F) 

srand: random number .... rand (3 F) 
srand: simple random-number . rand(3C) 
srand48, seed48. lcong48:/ . . . drand48(3C) 
sscanf: convert formatted . . . scanf(3S) 
ssignal, gsignal: software .... ssignal (3C) 
standard buffered input/output . stdioOS) 

standard interprocess stdipcOC) 

Standard (MIL-STD-1753).. . . mil(3F) 
stat: data returned by stat . . . stat (5) 

stat, fstat: get file status stat (2) 

stat system call stat (5) 

statistics ustat (2) 

status inquiries, ferror, .... ferror(3S) 

status stat (2) 

stdio: standard buffered .... stdio(3S) 

stime: set time stime(2) 

stop or terminate, wait: .... wait (2) 

strcat, strncat, strcmp, string (3C) 

strchr, strrchr, strpbrk,/ .... string (3 C) 
strcmp, strncmp, strcpy, .... string (3C) 
strcpy, strncpy, strlen,/ .... string (3 C) 

strcspn, strtok: string/ string(3C) 

stream, fclose, f close (3S) 

stream fopen (3S) 

stream, fseek, rewind, ftell: . . fseek(3S) 
stream, /getchar, fgetc, getw: . getc(3S) 

stream, gets, gets(3S) 

stream, /putchar, fputc, putw: . putc(3S) 

stream puts(3S) 

stream, setbuf, setbuf(3S) 
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/feof, clearerr, fileno: 
push character back into input 
long integer and base-64 ASCII 
lge, lgt, lie, lit: 
convert date and time to 
floating-point number to 
gps: graphical primitive 
gets, fgets: get a 
len: return length of Fortran 
puts, fputs: put a 
strspn, strcspn, strtok: 
number, strtod, atof: convert 
strtol, atol, atoi: convert 
/strncmp, strcpy, strncpy, 
strcpy, strncpy,/ strcat, 
strcat, strncat, strcmp, 
/strcmp, strncmp, strcpy, 
/strien, strchr, strrchr, 
/strncpy, strien, strchr, 
/strchr, strrchr, strpbrk, 
to double-precision number, 
/strpbrk, strspn, strcspn, 
string to integer, 
intro: introduction to 
/intrinsic functions and 
plot: graphics interface 
return location of Fortran 
sync: update 
interval, sleep: 
pause: 

swab: 

file/ ldgetname: retrieve 
name for common object file 
object/ /compute the index of a 
ldtbread: read an indexed 
syms: common object file 
object/ ldtbseek: seek to the 
symbol table format. 

error/ perror, errno, 
perror, errno, sys_errlist, 
binary search a sorted 
for common object file symbol 
/compute the index of a symbol 
file, /read an indexed symbol 
common object file symbol 
master device information 
mnttab: mounted file system 
ldtbseek: seek to the symbol 
hdestroy: manage hash search 
trigonometric/ sin, cos, 
intrinsic function, 
tan, dtan: Fortran 
/dtanh: Fortran hyperbolic 
hyperbolic tangent intrinsic/ 
sinh, cosh, 
search trees, tsearch, tfind, 
temporary file, tmpnam, 
tmpfile: create a 
tempnam: create a name for a 
terminals. 



stream status inquiries. . . 

stream, ungetc: 

string. /164a: convert between 
string comparison intrinsic/ 
string, /asctime, tzset: . . 
string, /fcvt, gcvt: convert 
string, format of graphical/ 
string from a stream. 

string 

string on a stream, 
string operations, /strpbrk, 
string to double-precision 
string to integer. . . . 
strien, strchr, strrchr,/ . 
strncat, strcmp, strncmp, 
strncmp, strcpy, strncpy,/ 
strncpy, strien, strchr,/ 
strpbrk, strspn, strcspn,/ 
strrchr, strpbrk, strspn./ 
strspn, strcspn, strtok:/ 
strtod, atof: convert string 
strtok: string operations, 
strtol, atol, atoi: convert 
subroutines and libraries, 
subroutines from the Fortran/ 

subroutines 

substring, index: .... 

super-block 

suspend execution for . . 
suspend process until signal. 

swab: swap bytes 

swap bytes 

symbol name for common object 
symbol table entry, /symbol . . 
symbol table entry of a common 
symbol table entry of a common/ 
symbol table format. . . 
symbol table of a common 
syms: common object file 
sync: update super-block, 
sys errlist, sys nerr: system 
sys nerr: system error/ 

tabTe. bsearch: 

table entry, /symbol name 
table entry of a common object/ 
table entry of a common object 
table format, syms: . 
table, master: . . . 

table 

table of a common object file, 
tables, hsearch, hcreate, . 
tan, asin, acos, atan, atan2: 
tan, dtan: Fortran tangent 
tangent intrinsic function, 
tangent intrinsic function, 
tanh, dtanh: Fortran . . 
tanh: hyperbolic functions, 
tdelete, twalk: manage binary 
tempnam: create a name for a 

temporary file 

temporary file, tmpnam, . . 
term: conventional names for 



ferror(3S) 
ungetc(3S) 
a641(3C) 
strcmp(3F) 
ctimeUC) 
ecvt(3C) 
gps (4) 
gets(3S) 
len(3F) 
puts(3S) 
string (3C) 
strtod (3C) 
strtol (3C) 
string (3C) 
string (3 C) 
string (3C) 
string (3C) 
string (3C) 
string (3C) 
string (3C) 
strtod (3C) 
string (3C) 
strtolOO 
intro (3) 
mil(3F) 
plot(3X) 
index (3 F) 
sync (2) 
sleep (3C) 
pause (2) 
swab(3C) 
swab(3C) 
ldgetname (3X) 
ldgetname (3X) 
ldtbindex(3X) 
ldtbread (3X) 
syms (4) 
ldtbseek (3X) 
syms (4) 
sync (2) 
perror (3 C) 
perror(3C) 
bsearch (3C) 
ldgetname (3X) 
ldtbindexOX) 
ldtbread (3X) 
syms (4) 
master (4) 
mnttab (4) 
ldtbseek(3X) 
hsearch (3C) 
trig(3M) 
tan(3F) 
tan(3F) 
tanh (3 F) 
tanh(3F) 
sinh(3M) 
tsearch (3C) 
tmpnam (3S) 
tmpfile (3S) 
tmpnam (3S) 
term (5) 
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term: format of compiled 
file., 
terminfo: 
generate file name for 
dial: establish an out-going 
getty. gettydefs: speed and 
isatty: find name of a 
term: conventional names for 
abort: 
exit, exit: 
for child process to stop or 
data base, 
fspec: format specification in 
plock: lock process, 
binary search trees, tsearch, 
mclock: return Fortran 

profil: execution 
up an environment at login 
stime: set 
time: get 
tzset: convert date and 
clock: report CPU 
process times, 
get process ana child process 
file access and modification 
file. 

for a temporary file, 
/tolower, toupper, ^tolower, 
popen, pclose: initiate pipe 
toupper, tolower, toupper, 
toascii: translate/ toupper, 
translate/ toupper, tolower. 
tolower, toascii: translate/ 
ptrace: process 
sign, isign, dsign: Fortran 
/ toupper, tolower, toascii: 
ftw: walk a file 
twalk: manage binary search 
tan, asin, acos, atan, atan2: 
language, 
files for device-independent 
typesetting viewgraphs/ mv: a 
twalk: manage binary search/ 
a terminal, 
utmp file of the current/ 
tsearch, tfind, tdelete, 
ichar, char: explicit Fortran 
types. 

types: primitive system data 
mv: a troff macro package for 
/localtime, gmtime, asctime, 
getpw: get name from 
limits, 
creation mask. 

UNIX system, 
into input stream. 
/seed48, lcong48: generate 
mktemp: make a 
entry, 
umount: 



term file » . term (4) 

term: format of compiled term . term (4) 

terminal capability data base. . terminfo (4) 

terminal, ctermid: ctermiduS) 

terminal line connection dial(3C) 

terminal settings used by ... gettydefs (4) 

terminal, ttyname, ttyname(3C) 

terminals. term (5) 

terminate Fortran program. . . abort(3F) 

terminate process exit (2) 

terminate, wait: wait wait (2) 

terminfo: terminal capability . . terminfo(4) 

text files fspec (4) 

text, or data in memory plock (2) 

tfind, tdelete, twalk: manage . . tsearch (30 

time accounting mclock(3F) 

time: get time time (2) 

time profile profil (2) 

time, profile: setting profile (4) 

time stime (2) 

time time (2) 

time to string, /asctime, .... ctime(3C) 

time used clock(30 

times: get process and child . . times (2) 

times, times: times (2) 

times, utime: set utime(2) 

tmpfile: create a temporary . . . tmpfile(3S) 

tmpnam, tempnam: create a name tmpnam(3S) 

toascii: translate characters. . . conv(3C) 

to/from a process popen (3S) 

tolower, toascii: translate/ . . . conv(3C) 

tolower, toupper, tolower, . . conv(3C) 

toupper, tolower, toascii: . . . conv(3C) 

toupper, tolower, toupper, . . . conv(3C) 

trace ptrace (2) 

transfer-of-sign intrinsic/ . . . sign (3 F) 

translate characters conv(3C) 

tree ftw(3C) 

trees, /tfind, tdelete, tsearch (30 

trigonometric functions, /cos, . trig(3M) 

troff: description of output . . . troff (5) 

troff. font: description font (5) 

troff macro package for .... mv(5) 

tsearch, tfind, tdelete, tsearch (30 

ttyname, isatty: find name of . . ttyname (30 

ttyslot: find the slot in the ... ttyslot(3C) 

twalk: manage binary search/ . tsearch (30 

type conversion, /dcmplx, . . . ftype(3F) 

types: primitive system data . . types (5) 

types types (5) 

typesetting viewgraphs and/ . . mv(5) 

tzset: convert date and time/ . . ctime(3C) 

UID getpw (30 

ulimit: get and set user .... ulimit(2) 

umask: set and get file umask(2) 

umount: unmount a file system. . umount (2) 

uname: get name of current . . uname(2) 

ungetc: push character back . . ungetc(3S) 

uniformly distributed/ drand48(3C) 

unique file name mktemp (30 

unlink: remove directory .... unlink (2) 

unmount a file system umount (2) 
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lfind: linear search and 
sync: 

setuid, setgid: set 
character login name of the 
/getgid, getegid: get real 
environ: 
ulimit: get and set 
logname: return login name of 
/get real user, effective 
the utmp file of the current 
statistics, 
modification times, 
utmp, wtmp: 
endutent, utmpname: access 
ttyslot: find the slot in the 
entry formats, 
/pututline, setutent, endutent, 
abs: return integer absolute 
cabs, zabs: Fortran absolute 
getenv: return 
ceiling, remainder, absolute 
putenv: change or add 
values. 

values: machine-dependent 
/print formatted output of a 
/print formatted output of a 
argument list, 
varargs: handle 
return Fortran environment 
option letter from argument 
assert: 

formatted output of/ vprintf, 
formatted output of/ vprintf, 
macro package for typesetting 
file system: format of system 
print formatted output of a/ 
print formatted output of a/ 
output of/ vprintf, vfprintf, 
output of/ vprintf, vfprintf, 
or terminate, wait: 
to stop or terminate. 

ftw: 

signal, signal: specify 
cndir: cnange 
get path-name of current 
write: 
putpwent: 

open: open for reading or 
utmp, wtmp: utmp and 
formats, utmp, 
Fortran Bitwise/ and, or, 
jO, jl, jn, 
jO, jl, jn, yO, 
j.0, jl, in, yO, yl, 
abs, labs, dabs, cabs, 



update, lsearch, lsearch(3C) 

update super-block sync (2) 

user and group IDs setuid (2) 

user, cuserid: get cuseridOS) 

user, effective user, real/ .... getuid(2) 

user environment environ (5) 

user limits ulimit (2) 

user logname (3X) 

user, real group, and/ getuid(2) 

user, /find the slot in ttyslotuC) 

ustat: get file system ustat(2) 

utime: set file access and .... utime(2) 

utmp and wtmp entry formats. . utmp (4) 

utmp file entry, /setutent, . . . getut(3C) 

utmp file of the current user. . . ttyslot ( 3 C) 

utmp, wtmp: utmp and wtmp . . utmp(4) 

utmpname: access utmp file/ . . getut(3C) 

value abs(3C) 

value, abs, iabs, dabs, abs(3F) 

value for environment name. . . getenv (3C) 

value functions, /fabs: floor, . . noor(3M) 

value to environment putenv (3C) 

values: machine-dependent . . . values (5) 

values values (5) 

varargs argument list vprintf(3S) 

varargs argument list vprintfGX) 

varargs: handle variable .... varargs(5) 

variable argument list varargs (5) 

variable, getenv: getenv (3 F) 

vector, getopt: get getopt (3C) 

verify program assertion assert(3X) 

vfprintf, vsprintf: print vprintf (3S) 

vfprintf, vsprintf: print vprintf (3 X) 

viewgraphs and slides, /troff . . mv(5) 

volume fs(4) 

vprintf, vfprintf, vsprintf: . . . vprintf(3S) 

vprintf, vfprintf, vsprintf: . . . vprintfGX) 

vsprintf: print formatted .... vprintf(3S) 

vsprintf: print formatted .... vprintf(3X) 

wait for child process to stop . . wait (2) 

wait: wait for child process . . . wait (2) 

walk a file tree ftw(3C) 

what to do upon receipt of a . . signal (2) 

working directory chdir (2) 

working directory, getcwd: . . . getcwduC) 

write on a file write (2) 

write password file entry. ... putpwent (3C) 

write: write on a file write (2) 

writing open (2) 

wtmp entry formats utmp (4) 

wtmp: utmp and wtmp entry . . utmp (4) 

xor, not, lshift, rshift: bool(3F) 

yO, yl, yn: Bessel functions. . . bessel(3M) 

yl, yn: Bessel functions bessel (3 M) 

yn: Bessel functions bessel (3 M) 

zabs: Fortran absolute value. . . abs(3F) 
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NAME 

intro — introduction to system calls and error numbers 

SYNOPSIS 

#include <errno.h> 

DESCRIPTION 

This section describes all of the system calls. Most of these calls 
have one or more error returns. An error condition is indicated by 
an otherwise impossible returned value. This is almost always — 1; 
the individual descriptions specify the details. An error number is 
also made available in the external variable errno. Errno is not 
cleared on successful calls, so it should be tested only after an 
error has been indicated. 

Each system call description attempts to list all possible error 
numbers. The following is a complete list of the error numbers 
and their names as defined in <errno.h>. 

1 EPERM Not owner 

Typically this error indicates an attempt to modify a file 
in some way forbidden except to its owner or super-user. 
It is also returned for attempts by ordinary users to do 
things allowed only to the super-user. 

2 ENOENT No such file or directory 

This error occurs when a file name is specified and the file 
should exist but doesn't, or when one of the directories in 
a path name does not exist. 

3 ESRCH No such process 

No process can be found corresponding to that specified 
by pid in kill or ptrace. 

4 EINTR Interrupted system call 

An asynchronous signal (such as interrupt or quit), which 
the user has elected to catch, occurred during a system 
call. If execution is resumed after processing the signal, it 
will appear as if the interrupted system call returned this 
error condition. 

5 EIO I/O error 

Some physical I/O error has occurred. This error may in 
some cases occur on a call following the one to which it 
actually applies. 

6 ENXIO No such device or address 

I/O on a special file refers to a subdevice which does not 
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exist, or beyond the limits of the device. It may also occur 
when, for example, a tape drive is not on-line or no disk 
pack is loaded on a drive. 

7 E2BIG Arg list too long 

An argument list longer than 5,120 bytes is presented to a 
member of the exec family. 

8 ENOEXEC Exec format error 

A request is made to execute a file which, although it has 
the appropriate permissions, does not start with a valid 
magic number [see a.out(4)]. 

9 EBADF Bad file number 

Either a file descriptor refers to no open file, or a read 
(respectively, write) request is made to a file which is open 
only for writing (respectively, reading). 

10 ECHILD No child processes 

A wait was executed by a process that had no existing or 
unwaited-for child processes. 

1 1 EAGAIN No more processes 

A fork failed because the system's process table is full or 
the user is not allowed to create any more processes. 

12 ENOMEM Not enough space 

During an exec, brk, or sbrk, a program asks for more 
space than the system is able to supply. This is not a tem- 
porary condition; the maximum space size is a system 
parameter. The error may also occur if the arrangement 
of text, data, and stack segments requires too many seg- 
mentation registers, or if there is not enough swap space 
during a fork. 

13 EACCES Permission denied 

An attempt was made to access a file in a way forbidden 
by the protection system. 

14 EFAULT Bad address 

The system encountered a hardware fault in attempting to 
use an argument of a system call. 

15 ENOTBLK Block device required 

A non-block file was mentioned where a block device was 
required, e.g., in mount. 
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16 EBUSY Device or resource busy 

An attempt was made to mount a device that was already 
mounted or an attempt was made to dismount a device on 
which there is an active file (open file, current directory, 
mounted-on file, active text segment). It will also occur if 
an attempt is made to enable accounting when it is 
already enabled. The device or resource is currently una- 
vailable. 

17 EEXIST File exists 

An existing file was mentioned in an inappropriate con- 
text, e.g., link. 

18 EXDEV Cross-device link 

A link to a file on another device was attempted. 

19 ENODEV No such device 

An attempt was made to apply an inappropriate system 
call to a device; e.g., read a write-only device. 

20 ENOTDIR Not a directory 

A non-directory was specified where a directory is 
required, for example in a path prefix or as an argument 
to chdir il). 

21 EISDIR Is a directory 

An attempt was made to write on a directory. 

22 EINVAL Invalid argument 

Some invalid argument (e.g., dismounting a non-mounted 
device; mentioning an undefined signal in signal, or kill; 
reading or writing a file for which Iseek has generated a 
negative pointer) was attempted. The math functions 
described in the (3M) entries of this manual causes the 
invalid argument to be set. 

23 ENFILE File table overflow 

The system file table is full, and temporarily no more 
opens can be accepted. 

24 EMFILE Too many open files 

No process may have more than 20 file descriptors open at 
a time. When a record lock is being created with fcntl, 
there are too many files with record locks on them. 

25 ENOTTY Not a character device 

An attempt was made to ioctl(2) a file that is not a spe- 
cial character device. 
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26 ETXTBSY Text file busy 

An attempt was made to execute a pure-procedure pro- 
gram that is currently open for writing. Also an attempt 
to open for writing a pure-procedure program that is being 
executed. 

27 EFBIG File too large 

The size of a file exceeded the maximum file size 
(1,082,201,088 bytes) or ULIMIT; see ulimitil). 

28 ENOSPC No space left on device 

During a write to an ordinary file, there is no free space 
left on the device. In fcntl, the setting or removing of 
record locks on a file cannot be accomplished because 
there are no more record entries left on the system. 

29 ESPIPE Illegal seek 

An Iseek was issued to a pipe. 

30 EROFS Read-only file system 

An attempt to modify a file or directory was made on a 
device mounted read-only. 

31 EMLINK Too many links 

An attempt to make more than the maximum number of 
links (1000) to a file. 

32 EPIPE Broken pipe 

A write on a pipe for which there is no process to read the 
data. This condition normally generates a signal; the error 
is returned if the signal is ignored. 

33 EDOM Math argument 

The argument of a function in the math package (3M) is 
out of the domain of the function. 

34 ERANGE Result too large 

The value of a function in the math package (3M) is not 
representable within machine precision. 

35 ENOMSG No message of desired type 

An attempt was made to receive a message of a type that 
does not exist on the specified message queue; see 
msgop(2). 
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36 EIDRM Identifier Removed 

This error is returned to processes that resume execution 
due to the removal of an identifier from the file system's 
name space [see msgctlil), semctKl), and shmctlil)]. 

45 EDEADLK Deadlock 

A deadlock situation was detected and avoided. 

DEFINITIONS 
Process ID 

Each active process in the system is uniquely identified by a posi- 
tive integer called a process ID. The range of this ID is from 1 to 
30,000. 

Parent Process ID 

A new process is created by a currently active process; see fork (2). 
The parent process ID of a process is the process ID of its creator. 

Process Group ID 

Each active process is a member of a process group that is 
identified by a positive integer called the process group ID. This 
ID is the process ID of the group leader. This grouping permits 
the signaling of related processes; see kill (2) . 

Tty Group ID 

Each active process can be a member of a terminal group that is 
identified by a positive integer called the tty group ID. This 
grouping is used to terminate a group of related processes upon 
termination of one of the processes in the group; see exit (2) and 
signal (2). 

Real User ID and Real Group ID 

Each user allowed on the system is identified by a positive integer 
called a real user ID. 

Each user is also a member of a group. The group is identified by 
a positive integer called the real group ID. 

An active process has a real user ID and real group ID that are set 
to the real user ID and real group ID, respectively, of the user 
responsible for the creation of the process. 

Effective User ID and Effective Group ID 

An active process has an effective user ID and an effective group 
ID that are used to determine file access permissions (see below). 
The effective user ID and effective group ID are equal to the 
process's real user ID and real group ID respectively, unless the 
process or one of its ancestors evolved from a file that had the set- 
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user-ID bit or set-group ID bit set; see exec (2) . 
Super-user 

A process is recognized as a super-user process and is granted spe- 
cial privileges if its effective user ID is 0. 

Special Processes 

The processes with a process ID of 0 and a process ID of 1 are spe- 
cial processes and are referred to as procO and prod. 

ProcO is the scheduler. Prod is the initialization process Unit). 
Procl is the ancestor of every other process in the system and is 
used to control the process structure. 

File Descriptor 

A file descriptor is a small integer used to do I/O on a file. The 
value of a file descriptor is from 0 to 19. A process may have no 
more than 20 file descriptors (0-19) open simultaneously. A file 
descriptor is returned by system calls such as open(2), or piped). 
The file descriptor is used as an argument by calls such as read(2), 
write (2), ioctl(2), and closed). 

File Name 

Names consisting of 1 to 14 characters may be used to name an 
ordinary file, special file, or directory. 

These characters may be selected from the set of all character 
values excluding \0 (null) and the ASCII code for / (slash) . 

Note that it is generally unwise to use *, ?, I, or 1 as part of file 
names because of the special meaning attached to these characters 
by the shell. See sh(l). Although permitted, it is advisable to 
avoid the use of unprintable characters in file names. 

Path Name and Path Prefix 

A path name is a null-terminated character string starting with an 
optional slash (/), followed by zero or more directory names 
separated by slashes; optionally followed by a file name. 

More precisely, a path name is a null-terminated character string 
constructed as follows: 

<path-name>::=<file-name> | <path-prefix> <file-name>|/ 
<path-prefix> :: 5 =<rtprefix> | /<rtprefix> 
<rtprefix>::— <dirname>/| <rtprefix> <dirname>/ 

where < file-name > is a string of 1 to 14 characters other than 
the ASCII slash and null, and <dirname> is a string of 1 to 14 
characters with the same restrictions) that names a directory. 
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If a path name begins with a slash, the path search begins at the 
root directory. Otherwise, the search begins from the current 
working directory. 

A slash by itself names the root directory. 

Unless specifically stated otherwise, the null path name is treated 
as if it named a non-existent file. 

Directory 

Directory entries are called links. By convention, a directory con- 
tains at least two links, . and .., referred to as dot and dot-dot 
respectively. Dot refers to the directory itself and dot-dot refers to 
its parent directory. 

Root Directory and Current Working Directory 

Each process has associated with it a concept of a root directory 
and a current working directory for the purpose of resolving path 
name searches. The root directory of a process need not be the 
root directory of the root file system. 

File Access Permissions 

Read, write, and execute/search permissions on a file are granted 
to a process if one or more of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches the user ID of 
the owner of the file and the appropriate access bit of the 
"owner" portion (0700) of the file mode is set. 

The effective user ID of the process does not match the 
user ID of the owner of the file, and the effective group ID 
of the process matches the group of the file and the 
appropriate access bit of the "group" portion (070) of the 
file mode is set. 

The effective user ID of the process does not match the 
user ID of the owner of the file, and the effective group ID 
of the process does not match the group ID of the file, and 
the appropriate access bit of the "other" portion (07) of 
the file mode is set. 

Otherwise, the corresponding permissions are denied. 

Message Queue Identifier 

A message queue identifier (msqid) is a unique positive integer 
created by a msgget(2) system call. Each msqid has a message 
queue and a data structure associated with it. The data structure 
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is referred to as msqid_ds and contains the following members: 



struct 


ipc_perm msg_perm; 


/* operation permission struct */ 


ushort 


msgjqnum; 


/* number of msgs on q */ 


ushort 


msgqbytes; 


/* max number of bytes on q */ 


ushort 


msglspid; 


/* pid of last msgsnd operation */ 


ushort 


msglrpid; 


/* pid of last msgrcv operation */ 


timet 


msgstime; 


/* last msgsnd time */ 


timet 


msgrtime; 


/* last msgrcv time */ 


timet 


msgctime; 


/* last change time */ 






/* Times measured in sees since */ 






/* 00:00:00 GMT, Jan. 1, 1970 */ 



Msg_perm is an ipc_perm structure that specifies the message 
operation permission (see below). This structure includes the fol- 
lowing members: 



ushort 


cuid; 


/* 


creator user id */ 


ushort 


cgid; 


/* 


creator group id */ 


ushort 


uid; 


/* 


user id */ 


ushort 


gid; 


/* 


group id */ 


ushort 


mode; 


/* 


r/w permission */ 



Msgjqnum is the number of messages currently on the queue. 
Msg_qbytes is the maximum number of bytes allowed on the 
queue. Msgjspid is the process id of the last process that per- 
formed a msgsnd operation. Msgjrpid is the process id of the last 
process that performed a msgrcv operation. Msg_stime is the time 
of the last msgsnd operation, msg rtime is the time of the last 
msgrcv operation, and msg_ctime is the time of the last msgctl (2) 
operation that changed a member of the above structure. 

Message Operation Permissions 

In the msgopil) and msgctl '(2) system call descriptions, the per- 
mission required for an operation is given as "{token}", where 
"token" is the type of permission needed interpreted as follows: 



00400 Read by user 

00200 Write by user 

00060 Read, Write by group 

00006 Read, Write by others 



Read and Write permissions on a msqid are granted to a process if 
one or more of the following are true: 

The effective user ID of the process is super-user. 
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The effective user ID of the process matches 
msg_perm.[cluid in the data structure associated with 
msqid and the appropriate bit of the "user" portion 
(0600) of msg_perm.mode is set. 

The effective user ID of the process does not match 
msg_perm.[cluid and the effective group ID of the process 
matches msg_perm.[c]gid and the appropriate bit of the 
"group" portion (060) of msgjperm.mode is set. 

The effective user ID of the process does not match 
msg_perm.[c]uid and the effective group ID of the process 
does not match msg_perm.[dgid and the appropriate bit of 
the "other" portion (06) of msg_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 

Semaphore Identifier 

A semaphore identifier (semid) is a unique positive integer created 
by a semgetil) system call. Each semid has a set of semaphores 
and a data structure associated with it. The data structure is 
referred to as semid_ds and contains the following members: 

struct ipc_perm sem_perm; /* operation permission struct */ 
ushort sem_nsems; /* number of sems in set */ 

time t sem otime; /* last operation time */ 

time t sem ctime; /* last change time */ 

/ * Times measured in sees since */ 
/* 00:00:00 GMT, Jan. 1, 1970 */ 

Semjperm is an ipc_perm structure that specifies the semaphore 
operation permission (see below). This structure includes the fol- 
lowing members: 



ushort 


cuid; 


/* 


creator user id */ 


ushort 


cgid; 


/* 


creator group id */ 


ushort 


uid; 


/* 


user id */ 


ushort 


gid; 


/* 


group id */ 


ushort 


mode; 


/* 


r/a permission */ 



The value of semnsems is equal to the number of semaphores in 
the set. Each semaphore in the set is referenced by a positive 
integer referred to as a sem num. Semjium values run sequen- 
tially from 0 to the value of sem nsems minus 1 . Sem_otime is the 
time of the last semop(2) operation, and sem_ctime is the time of 
the last semctlil) operation that changed a member of the above 
structure. 
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A semaphore is a data structure that contains the following 
members: 



ushort semncnt; /* # awaiting semval > cval */ 
ushort semzcnt; /* # awaiting semval — 0 */ 

Semval is a non-negative integer. Sempid is equal to the process 
ID of the last process that performed a semaphore operation on 
this semaphore. Semncnt is a count of the number of processes 
that are currently suspended awaiting this semaphore's semval to 
become greater than its current value. Semzcnt is a count of the 
number of processes that are currently suspended awaiting this 
semaphore's semval to become zero. 

Semaphore Operation Permissions 

In the semopil) and semctl(2) system call descriptions, the per- 
mission required for an operation is given as "{token}", where 
"token" is the type of permission needed interpreted as follows: 



Read and Alter permissions on a semid are granted to a process if 
one or more of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches 
sem_perm.[c]uid in the data structure associated with 
semid and the appropriate bit of the "user" portion 
(0600) of semjperm.mode is set. 

The effective user ID of the process does not match 
sem_perm.lcluid and the effective group ID of the process 
matches sem_perm.[c]gid and the appropriate bit of the 
"group" portion (060) of sem_perm.mode is set. 

The effective user ID of the process does not match 
sem_perm.[cluid and the effective group ID of the process 
does not match sem_perm.lclgid and the appropriate bit of 
the "other" portion (06) of semjperm.mode is set. 

Otherwise, the corresponding permissions are denied. 



ushort 
short 



semval; 
sempid; 



/* semaphore value */ 
/* pid of last operation */ 



00400 
00200 
00060 
00006 



Read by user 
Alter by user 
Read, Alter by group 
Read, Alter by others 
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Shared Memory Identifier 

A shared memory identifier (shmid) is a unique positive integer 
created by a shmget (2) system call. Each shmid has a segment of 
memory (referred to as a shared memory segment) and a data 
structure associated with it. The data structure is referred to as 
shmid ds and contains the following members: 



struct 


ipc_perm shmjperm; 


A 


operation permission struct */ 


int 


shm_segsz; 


A 


size of segment */ 


ushort 


shmcpid; 


A 


creator pid »/ 


ushort 


shmlpid; 


A 


pid of last operation */ 


short 


shmnattch; 


A 


number of current attaches */ 


timet 


shmatime; 


A 


last attach time */ 


timet 


shmdtime; 


A 


last detach time */ 


timet 


shmctime; 


A 


last change time */ 






A 


Times measured in sees since */ 






A 


00:00:00 GMT, Jan. 1, 1970 */ 



Shmjperm is an ipejperm structure that specifies the shared 
memory operation permission (see below). This structure includes 



the following members: 






ushort cuid; 


A 


creator user id */ 


ushort cgid; 


A 


creator group id */ 


ushort uid; 


A 


user id */ 


ushort gid; 


A 


group id */ 


ushort mode; 


A 


r/w permission */ 



Shmsegsz specifies the size of the shared memory segment. 
Shm cpid is the process id of the process that created the shared 
memory identifier. Shm lpid is the process id of the last process 
that performed a shmop(2) operation. Shm nattch is the number 
of processes that currently have this segment attached. Shm atime 
is the time of the last shmat operation, shm dtime is the time of 
the last shmdt operation, and shm ctime is the time of the last 
shmctl (2) operation that changed one of the members of the above 
structure. 

Shared Memory Operation Permissions 

In the shmop(2) and shmctl (2) system call descriptions, the per- 
mission required for an operation is given as "{token}", where 
"token" is the type of permission needed interpreted as follows: 

00400 Read by user 

00200 Write by user 
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00060 
00006 



Read, Write by group 
Read, Write by others 



Read and Write permissions on a shmid are granted to a process if 
one or more of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches 
shmjperm.lcluid in the data structure associated with 
shmid and the appropriate bit of the "user" portion 
(0600) of shmjperm.mode is set. 

The effective user ID of the process does not match 
shmjperm.lcluid and the effective group ID of the process 
matches shmjperm.lclgid and the appropriate bit of the 
"group" portion (060) of shmjperm.mode is set. 

The effective user ID of the process does not match 
shmjperm.lcluid and the effective group ID of the process 
does not match shmjperm.lclgid and the appropriate bit of 
the "other" portion (06) of shmjperm.mode is set. 

Otherwise, the corresponding permissions are denied. 

SEE ALSO 

close (2), ioctl(2), open (2), pipe (2), read (2), write (2), introO). 
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NAME 

access — determine accessibility of a file 

SYNOPSIS 

int access (path, amode) 
char *path; 
int amode; 

DESCRIPTION 

Path points to a path name naming a file. Access checks the 
named file for accessibility according to the bit pattern contained 
in amode, using the real user ID in place of the effective user ID 
and the real group ID in place of the effective group ID. The bit 
pattern contained in amode is constructed as follows: 

04 read 

02 write 

01 execute (search) 

00 check existence of file 

Access to the file is denied if one or more of the following are true: 
[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] Read, write, or execute (search) permission is 

requested for a null path name. 
[ENOENT] The named file does not exist. 
[EACCES] Search permission is denied on a component of the 

path prefix. 

[EROFS] Write access is requested for a file on a read-only 
file system. 

[ETXTBSY] Write access is requested for a pure procedure 
(shared text) file that is being executed. 

[EACCESS] Permission bits of the file mode do not permit 
the requested access. 

[EFAULT] Path points outside the allocated address 
space for the process. 

The owner of a file has permission checked with respect to the 
"owner" read, write, and execute mode bits Members of the file's 
group other than the owner have permissions checked with respect 
to the "group" mode bits, and all others have permissions checked 
with respect to the "other" mode bits. 
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RETURN VALUE 

If the requested access is permitted, a value of 0 is returned. Oth- 
erwise, a value of —1 is returned and errno is set to indicate the 
error. 

SEE ALSO 

chmod(2), stat(2). 
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NAME 



acct — enable or disable process accounting 

SYNOPSIS 

int acct (path) 
char *path; 

DESCRIPTION 

Acct is used to enable or disable the system process accounting 
routine. If the routine is enabled, an accounting record will be 
written on an accounting file for each process that terminates. 
Termination can be caused by one of two things: an exit call or a 
signal; see exit (2) and signal (2) . The effective user ID of the cal- 
ling process must be super-user to use this call. 

Path points to a path name naming the accounting file. The 
accounting file format is given in acct (4). 

The accounting routine is enabled if path is non-zero and no errors 
occur during the system call. It is disabled if path is zero and no 
errors occur during the system call. 

Acct will fail if one or more of the following are true: 

[EPERM] The effective user of the calling process is not 



[ENOTDIRl A component of the path prefix is not a directory. 



[EBUSY] 



super-user. 

An attempt is being made to enable accounting 
when it is already enabled. 



[ENOENT] 



One or more components of the accounting file 
path name do not exist. 

A component of the path prefix denies search 
permission. 

The file named by path is not an ordinary file. 

Mode permission is denied for the named 
accounting file. 

The named file is a directory. 

The named file resides on a read-only file system. 

Path points to an illegal address. 



[EACCES] 



[EACCESl 



[EACCES] 



[EISDIRl 



[EROFS] 



[EFAULTl 
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RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

exit (2), signal (2), acct(4). 
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NAME 

alarm — set a process alarm clock 

SYNOPSIS 

unsigned alarm (sec) 
unsigned sec; 

DESCRIPTION 

Alarm instructs the alarm clock of the calling process to send the 
signal SIGALRM to the calling process after the number of real 
time seconds specified by sec have elapsed; see signal (2) . 

Alarm requests are not stacked; successive calls reset the alarm 
clock of the calling process. 

If sec is 0, any previously made alarm request is canceled. 

RETURN VALUE 

Alarm returns the amount of time previously remaining in the 
alarm clock of the calling process. 

SEE ALSO 

pause (2), signal (2). 
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NAME 

brk, sbrk — change data segment space allocation 

SYNOPSIS 

int brk (endds) 
char *endds; 

char *sbrk (incr) 
int incr; 

DESCRIPTION 

Brk and sbrk are used to change dynamically the amount of space 
allocated for the calling process's data segment; see exec (2). The 
change is made by resetting the process's break value and allocat- 
ing the appropriate amount of space. The break value is the 
address of the first location beyond the end of the data segment. 
The amount of allocated space increases as the break value 
increases. The newly allocated space is set to zero. 

Brk sets the break value to endds and changes the allocated space 
accordingly. 

Sbrk adds incr bytes to the break value and changes the allocated 
space accordingly. Incr can be negative, in which case the amount 
of allocated space is decreased. 

Brk and sbrk will fail without making any change in the allocated 
space if one or more of the following are true: 

i Such a change would result in more space being allocated 
than is allowed by a system-imposed maximum (see 
ulimitil)). [ENOMEM] 

Such a change would result in the break value being 
greater than or equal to the start address of any attached 
shared memory segment (see shmopil)). 

RETURN VALUE 

Upon successful completion, brk returns a value of 0 and sbrk 
returns the old break value. Otherwise, a value of —1 is returned 
and errno is set to indicate the error. 

SEE ALSO 

exec (2), shmop(2), ulimit(2). 
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NAME 

chdir — change working directory 

SYNOPSIS 

int chdir (path) 
char *path; 

DESCRIPTION 

Path points to the path name of a directory. Chdir causes the 
named directory to become the current working directory, the 
starting point for path searches for path names not beginning with 
/. 

Chdir will fail and the current working directory will be 
unchanged if one or more of the following are true: 

[ENOTDIR] A component of the path name is not a directory. 

[ENOENTl The named directory does not exist. 

[EACCES] Search permission is denied for any component of 

the path name. 

[EFAULTl Path points outside the allocated address space of 
the process. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

chroot(2). 
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NAME 

chmod — change mode of file 

SYNOPSIS 

int chmod (path, mode) 
char *path; 
int mode; 

DESCRIPTION 

Path points to a path name naming a file. Chmod sets the access 
permission portion of the named file's mode according to the bit 
pattern contained in mode. 

Access permission bits are interpreted as follows: 

04000 Set user ID on execution. 

02000 Set group ID on execution. 

01000 Save text image after execution. 

00400 Read by owner. 

00200 Write by owner. 

00100 Execute (search if a directory) by owner. 

00070 Read, write, execute (search) by group. 

00007 Read, write, execute (search) by others. 

The effective user ID of the process must match the owner of the 
file or be super-user to change the mode of a file. 

If the effective user ID of the process is not super-user, mode bit 
01000 (save text image on execution) is cleared. 

If the effective user ID of the process is not super-user and the 
effective group ID of the process does not match the group ID of 
the file, mode bit 02000 (set group ID on execution) is cleared. 

If an executable file is prepared for sharing then mode bit 01000 
prevents the system from abandoning the swap-space image of the 
program-text portion of the file when its last user terminates. 
Thus, when the next user of the file executes it, the text need not 
be read from the file system but can simply be swapped in, saving 
time. 

Chmod will fail and the file mode will be unchanged if one or 
more of the following are true: 

[ENOTDIRl A component of the path prefix is not a directory. 
[ENOENT] The named file does not exist. 
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[EACCES] 



Search permission is denied on a component of 
the path prefix. 



[EPERM] 



The effective user ID does not match the owner 
of the file and the effective user ID is not super- 
user. 



[EROFS] 



The named file resides on a read-only file system. 

Path points outside the allocated address space of 
the process. 



[EFAULT] 



RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of — 1 is returned and errno is set to indicate the error. 

SEE ALSO 

chown(2), mknod(2). 
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NAME 

chown — change owner and group of a file 

SYNOPSIS 

int chown (path, owner, group) 

char «path; 

int owner, group; 

DESCRIPTION 

Path points to a path name naming a file. The owner ID and 
group ID of the named file are set to the numeric values contained 
in owner and group respectively. 

Only processes with effective user ID equal to the file owner or 
super-user may change the ownership of a file. 

If chown is invoked by other than the super-user, the set-user-ID 
and set-group-ID bits of the file mode, 04000 and 02000 respec- 
tively, will be cleared. 

Chown will fail and the owner and group of the named file will 
remain unchanged if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of 
the path prefix. 

[EPERM] The effective user ID does not match the owner 

of the file and the effective user ID is not super- 
user. 

[EROFSl The named file resides on a read-only file system. 

[EFAULT] Path points outside the allocated address space of 
the process. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

chmod(2). 

chown(l) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
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NAME 

chroot — change root directory 

SYNOPSIS 

int chroot (path) 
char *path; 

DESCRIPTION 

Path points to a path name naming a directory. Chroot causes 
the named directory to become the root directory, the starting 
point for path searches for path names beginning with /. The 
user's working directory is unaffected by the chroot system call. 

The effective user ID of the process must be super-user to change 
the root directory. 

The .. entry in the root directory is interpreted to mean the root 
directory itself. Thus, .. cannot be used to access files outside the 
subtree rooted at the root directory. 

Chroot will fail and the root directory will remain unchanged if 
one or more of the following are true: 

[ENOTDIR] Any component of the path name is not a direc- 
tory. 

[ENOENT] The named directory does not exist. 

[EPERM] The effective user ID is not super-user. 

[EFAULT] Path points outside the allocated address space of 
the process. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

chdir(2). 
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NAME 

close — close a file descriptor 

SYNOPSIS 

int close (Hides) 
int fildes; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, 
or pipe system call. Close closes the file descriptor indicated by 
fildes. All outstanding record locks owned by the process (on the 
file indicated by fildes) are removed. 

Close will fail if fildes is not a valid open file descriptor. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

creat (2), dup (2), exec (2), fcntl (2), open (2), pipe (2). 
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NAME 

creat — create a new file or rewrite an existing one 

SYNOPSIS 

int creat (path, mode) 
char *path; 
int mode; 

DESCRIPTION 

Creat creates a new ordinary file or prepares to rewrite an existing 
file named by the path name pointed to by path. 

If the file exists, the length is truncated to 0 and the mode and 
owner are unchanged. Otherwise, the file's owner ID is set to the 
effective user ID, of the process the group ID of the process is set 
to the effective group ID, of the process and the low-order 12 bits 
of the file mode are set to the value of mode modified as follows: 

All bits set in the process's file mode creation mask are 
cleared. See umaskil). 

The "save text image after execution bit" of the mode is 
cleared. See chmod (2) . 

Upon successful completion, the file descriptor is returned and the 
file is open for writing, even if the mode does not permit writing. 
The file pointer is set to the beginning of the file. The file descrip- 
tor is set to remain open across exec system calls. See fcntl(2). 
No process may have more than 20 files open simultaneously. A 
new file may be created with a mode that forbids writing. 

Creat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[EACCES] Search permission is denied on a component of 
the path prefix. 

[ENOENT] The path name is null. 

[EACCES] The file does not exist and the directory in which 
the file is to be created does not permit writing. 

[EROFS] The named file resides or would reside on a 

read-only file system. 

[ETXTBSY] The file is a pure procedure (shared text) file 
that is being executed. 
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[EACCES] 



The file exists and write permission is denied. 

The named file is an existing directory. 

Twenty (20) file descriptors are currently open. 

Path points outside the allocated address space of 
the process. 

The system file table is full. 



[EISDIR] 



[EMFILE] 



[EFAULT] 



[ENFILE] 



RETURN VALUE 

Upon successful completion, a non-negative integer, namely the file 
descriptor, is returned. Otherwise, a value of —1 is returned and 
errno is set to indicate the error. 

SEE ALSO 

chmod(2), close(2), dup(2), fcntl(2), lseek(2), open(2), read(2), 
umask(2), write (2). 



26— System Calls and Library Routines UNIX Programmer's Manual 



DUP(2) 



DUP(2) 



NAME 

dup — duplicate an open file descriptor 

SYNOPSIS 

int dup (fildes) 
int fildes; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup,fcntl, 
or pipe system call. Dup returns a new file descriptor having the 
following in common with the original: 

Same open file (or pipe) . 

Same file pointer (i.e., both file descriptors share one file 
pointer). 

Same access mode (read, write or read/ write). 

The new file descriptor is set to remain open across exec system 
calls. See fcntl(2). 

The file descriptor returned is the lowest one available. 
Dup will fail if one or more of the following are true: 
[EBADFl Fildes is not a valid open file descriptor. 

[EMFILE] Twenty (20) file descriptors are currently open. 

RETURN VALUE 

Upon successful completion a non-negative integer, namely the file 
descriptor, is returned. Otherwise, a value of —1 is returned and 
errno is set to indicate the error. 

SEE ALSO 

creat (2), close (2), exec (2), fcntl(2), open (2), pipe (2). 
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NAME 

execl, execv, execle, execve, execlp, execvp — execute a file 

SYNOPSIS 

int execl (path, argO, argl, argn, 0) 
char ♦path, *argO, *argl, *argn; 

int execv (path, argv) 
char * pa th, *argv[ j; 

int execle (path, argO, argl, argn, 0, envp) 
char *path, *argO, *argl, *argn, *envp[ 1; 

int execve (path, argv, envp) 
char ♦path, *argvl 1, *envp[ 1; 

int execlp (file, argO, argl, argn, 0) 
char *file, *argO, *argl, *argn; 

int execvp (file, argv) 
char *file, *argvl 1; 

DESCRIPTION 

Exec in all its forms transforms the calling process into a new pro- 
cess. The new process is constructed from an ordinary, executable 
file called the new process file. This file consists of a header (see 
a.out(4)), a text segment, and a data segment. The data segment 
contains an initialized portion and an uninitialized portion (bss). 
There can be no return from a successful exec because the calling 
process is overlaid by the new process. 

When a C program is executed, it is called as follows: 

main (argc, argv, envp) 
int argc; 

char **argv, **envp; 

where argc is the argument count and argv is an array of charac- 
ter pointers to the arguments themselves. As indicated, argc is 
conventionally at least one and the first member of the array 
points to a string containing the name of the file. 

Path points to a path name that identifies the new process file. 

File points to the new process file. The path prefix for this file is 
obtained by a search of the directories passed as the environment 
line "PATH =" (see environ(5)). The environment is supplied by 
the shell (see sh (1)). 



28— System Calls and Library Routines 



UNIX Programmer's Manual 



EXEC (2) 



EXEC (2) 



ArgO, argl, argn are pointers to null-terminated character 
strings. These strings constitute the argument list available to the 
new process. By convention, at least argO must be present and 
point to a string that is the same as path (or its last component) . 

Argv is an array of character pointers to null-terminated strings. 
These strings constitute the argument list available to the new pro- 
cess. By convention, argv must have at least one member, and it 
must point to a string that is the same as path (or its last com- 
ponent) . Argv is terminated by a null pointer. 

Envp is an array of character pointers to null-terminated strings. 
These strings constitute the environment for the new process. 
Envp is terminated by a null pointer. For execl and execv, the C 
run-time start-off routine places a pointer to the environment of 
the calling process in the global cell: 

extern char **environ; 
and it is used to pass the environment of the calling process to the 
new process. 

File descriptors open in the calling process remain open in the new 
process, except for those whose close-on-exec flag is set; see 
fcntl(2). For those file descriptors that remain open, the file 
pointer is unchanged. 

Signals set to terminate the calling process will be set to terminate 
the new process. Signals set to be ignored by the calling process 
will be set to be ignored by the new process. Signals set to be 
caught by the calling process will be set to terminate new process; 
see signal (2) . 

If the set-user-ID mode bit of the new process file is set (see 
chmod(2)), exec sets the effective user ID of the new process to 
the owner ID of the new process file. Similarly, if the set-group-ID 
mode bit of the new process file is set, the effective group ID of the 
new process is set to the group ID of the new process file. The real 
user ID and real group ID of the new process remain the same as 
those of the calling process. 

The shared memory segments attached to the calling process will 
not be attached to the new process (see shmop(2)). 

Profiling is disabled for the new process; see profil (2) . 

The new process also inherits the following attributes from the cal- 
ling process: 
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nice value (see nice (2)) 

process ID 

parent process ID 

process group ID 

semadj values (see semopil)) 

tty group ID (see exit (2) and signal (2)) 

trace flag (see ptrace(2) request 0) 

time left until an alarm clock signal (see alarm (2)) 

current working directory 

root directory 

file mode creation mask (see umask{2)) 

file size limit (see ulimit{2)) 

utime, stime, cutime, and cstime (see times (2)) 

Exec will fail and return to the calling process if one or more of 
the following are true: 

[ENOENT] One or more components of the new process path 
name of the file do not exist. 

[ENOTDIR] A component of the new process path of the file 
prefix is not a directory. 

[EACCES] Search permission is denied for a directory listed 
in the new process file's path prefix. 

[EACCES] The new process file is not an ordinary file. 

[EACCES] The new process file mode denies execution per- 
mission. 

[ENOEXEC] The exec is not an execlp or execvp , and the new 
process file has the appropriate access permission 
but an invalid magic number in its header. 

[ETXTBSY] The new process file is a pure procedure (shared 
text) file that is currently open for writing by 
some process. 

[ENOMEM] The new process requires more memory than is 
allowed by the system-imposed maximum MAX- 
MEM. 

[E2BIG1 The number of bytes in the new process's argu- 

ment list is greater than the system-imposed limit 
of 5120 bytes. 
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[EFAULT] 



The new process file is not as long as indicated 
by the size values in its header. 

Path, argv, or envp point to an illegal address. 



[EFAULT] 



RETURN VALUE 

If exec returns to the calling process an error has occurred; the 
return value will be — 1 and errno will be set to indicate the error. 

SEE ALSO 

alarm (2), exit (2), fork(2), nice(2), ptrace(2), semop(2), signal (2), 
times (2), ulimit(2), umask(2), a. out (4), environ (5). 
sh(l) in the UNIX Programmer's Manual— Volume 1: Commands 
and Utilities. 
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NAME 

exit, _exit — terminate process 

SYNOPSIS 

void exit (status) 
int status; 
void exit (status) 
int status; 

DESCRIPTION 

Exit terminates the calling process with the following conse- 
quences: 

All of the file descriptors open in the calling process are 
closed. 

If the parent process of the calling process is executing a 
wait, it is notified of the calling process's termination and 
the low order eight bits (i.e., bits 0377) of status are 
made available to it; see wait (2) . 

If the parent process of the calling process is not executing 
a wait, the calling process is transformed into a zombie 
process. A zombie process is a process that only occupies 
a slot in the process table. It has no other space allocated 
either in user or kernel space. The process table slot that 
it occupies is partially overlaid with time accounting infor- 
mation (see <sys/proc.h>) to be used by times. 

The parent process ID of all of the calling process's exist- 
ing child processes and zombie processes is set to 1. This 
means the initialization process (see introil)) inherits 
each of these processes. 

Each attached shared memory segment is detached and 
the value of shmnattach in the data structure associated 
with its shared memory identifier is decremented by 1 . 

For each semaphore for which the calling process has set a 
semadj value (see semop(2)), that semadj value is added 
to the semval of the specified semaphore. 

If the process has a process, text, or data lock, an unlock 
is performed (see plock(2)). 

An accounting record is written on the accounting file if 
the system's accounting routine is enabled; see acct (2) . 
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If the process ID, tty group ID, and process group ID of 
the calling process are equal, the SIGHUP signal is sent to 
each process that has a process group ID equal to that of 
the calling process. 

The C function exit may cause cleanup actions before the process 
exits. The function _exit circumvents all cleanup. 

SEE ALSO 

acct(2), intro(2), plock(2), semop(2), signal (2), wait (2). 

WARNING 

See WARNING in signal (2). 
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NAME 



fcntl — file control 



SYNOPSIS 

#include <fcntl.h> 

int fcntl (fildes, cmd, arg) 
int fildes, cmd, arg; 

DESCRIPTION 

Fcntl provides for control over open files. Fildes is an open file 
descriptor obtained from a creat, open, dup, fcntl, or pipe system 
call. 

The commands available are: 

F DUPFD Return a new file descriptor as follows: 

Lowest numbered available file descriptor greater 
than or equal to arg. 

Same open file (or pipe) as the original file. 

Same file pointer as the original file (i.e., both file 
descriptors share one file pointer) . 

Same access mode (read, write, or read/ write). 

Same file status flags (i.e., both file descriptors 
share the same file status flags) . 

The close-on-exec flag associated with the new file 
descriptor is set to remain open across exec (2) 
system calls. 

FGETFD Get the close-on-exec flag associated with the file 
descriptor fildes. If the low-order bit is 0 the file 
will remain open across exec, otherwise the file 
will be closed upon execution of exec. 

F SETFD Set the close-on-exec flag associated with fildes to 

the low-order bit of arg (0 or 1 as above) . 

F GETFL Get file status flags. 

F SETFL Set file status flags to arg. Only certain flags can 

be set; see fcntl (5). 

F GETLK Get the first lock which blocks the lock descrip- 
tion given by the variable of type struct flock 
pointed to by arg. The information retrieved 
overwrites the information passed to fcntl in the 
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flock structure. If no lock is found that would 
prevent this lock from being created, then the 
structure is passed back unchanged except for the 
lock type which will be set to F UNLCK. 

FSETLK Set or clear a file segment lock according to the 

variable of type struct flock pointed to by arg [see 
fcntl(5)]. The cmd F SETLK is used to establish 
read (F_RDLCK) and write (F_WRLCK) locks, as 
well as remove either type of lock (F_UNLCK). 
If a read or write lock cannot be set, fcntl will 
return immediately with an error value of —1. 

FSETLKW This cmd is the same as F SETLK except that if a 
read or write lock is blocked by other locks, the 
process will sleep until the segment is free to be 
locked. 

A read lock prevents any process from write locking the protected 
area. More than one read lock may exist for a given segment of a 
file at a given time. The file descriptor on which a read lock is 
being placed must have been opened with read access. 

A write lock prevents any process from read locking or write lock- 
ing the protected area. Only one write lock may exist for a given 
segment of a file at a given time. The file descriptor on which a 
write lock is being placed must have been opened with write 
access. 

The structure flock describes the type Qtype), starting offset 
Ujvhence), relative offset (i start), size (I Jen), and process id 
0 _pid) of the segment of the file to be affected. The process id 
field is only used with the F GETLK cmd to return the value for a 
block in lock. Locks may start and extend beyond the current end 
of a file, but may not be negative relative to the beginning of the 
file. A lock may be set to always extend to the end of file by set- 
ting I Jen to zero (0). If such a lock also has Ijtart set to zero 
(0), the whole file will be locked. Changing or unlocking a seg- 
ment from the middle of a larger locked segment leaves two 
smaller segments for either end. Locking a segment that is 
already locked by the calling process causes the old lock type to be 
removed and the new lock type to take affect. All locks associated 
with a file for a given process are removed when a file descriptor 
for that file is closed by that process or the process holding that 
file descriptor terminates. Locks are not inherited by a child 
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process in a fork(2) system call. 
Fcntl will fail if one or more of the following are true: 

Fildes is not a valid open file descriptor. 

Cmd is FDUPFD and 20 file descriptors are 
currently open. 

Cmd is F_DUPFD and arg is negative or greater 
than 20. 

Cmd is FGETLK, FSETLK, or SETLKW and arg 
or the data it points to is not valid. 

Cmd is F SETLK the type of lock Ujype) is a 
read (F_RDLCK) or write (F_WRLCK) lock and 
the segment of a file to be locked is already write 
locked by another process or the type is a write 
lock and the segment of a file to be locked is 
already read or write locked by another process. 

Cmd is F SETLK or FSETLKW, the type of lock 
is a read or write lock and there are no more file 
locking headers available (too many files have 
segments locked). 

Cmd is F SETLK or F SETLKW, the type of lock 
is a read or write lock and there are no more file 
locking headers available (too many files have 
segments locked) or there are no more record 
locks available (too many file segments locked) . 

[EDEADLK] Cmd is F SETLK, when the lock is blocked by 
some lock from another process and sleeping 
(waiting) for that lock to become free, this 
causes a deadlock situation. 

RETURN VALUE 

Upon successful completion, the value returned depends on cmd as 
follows: 

F DUPFD A new file descriptor. 
F GETFD Value of flag (only the low-order bit is 

defined). 

F SETFD Value other than - 1 . 

F GETFL Value of file flags. 
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[EMFILE] 

[EINFILE] 

[EINVAL] 

[EACCESS] 

[EMFILE] 
[ENOSPCl 
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FSETFL Value other than -1. 

F_GETLK Value other that - 1 . 

FSETLK Value other than - 1 . 

F SETLKW Value other than - 1 . 
Otherwise, a value of —1 is returned and errno is set to indicate 
the error. 

SEE ALSO 

close (2), exec (2), open (2), fcntl(5). 
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NAME 

fork — create a new process 

SYNOPSIS 

int fork () 

DESCRIPTION 

Fork causes creation of a new process. The new process (child 
process) is an exact copy of the calling process (parent process). 
This means the child process inherits the following attributes from 
the parent process: 

environment 

close-on-exec flag (see exec (2)) 

signal handling settings (i.e., SIG DFL, SIGJNG, function 
address) 

set-user-ID mode bit 
set-group-ID mode bit 
profiling on/off status 
nice value (see nice (2)) 

all attached shared memory segments (see shmop(2)) 
process group ID 

tty group ID (see exit (2) and signal (2)) 

trace flag (see ptrace{2) request 0) 

time left until an alarm clock signal (see alarm (2)) 

current working directory 

root directory 

file mode creation mask (see umask(2)) 
file size limit (see ulimit{2)) 

The child process differs from the parent process in the following 
ways: 

The child process has a unique process ID. 

The child process has a different parent process ID (i.e., 
the process ID of the parent process) . 

The child process has its own copy of the parent's file 
descriptors. Each of the child's file descriptors shares a 
common file pointer with the corresponding file descriptor 
of the parent. 

All semadj values are cleared (see semop(2)). 

Process locks, text locks and data locks are not inherited 
by the child (see plock(2)). 
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The child process's utime, stime, cutime, and cstime are 
set to 0. The time left until an alarm clock signal is reset 
to 0. 

Fork will fail and no child process will be created if one or more 
of the following are true: 

[EAGAIN] The system-imposed limit on the total number of 
processes under execution would be exceeded. 

[EAGAIN] The system-imposed limit on the total number of 
processes under execution by a single user would 
be exceeded. 

RETURN VALUE 

Upon successful completion, fork returns a value of 0 to the child 
process and returns the process ID of the child process to the 
parent process. Otherwise, a value of —1 is returned to the parent 
process, no child process is created, and errno is set to indicate the 
error. 

SEE ALSO 

exec (2), nice (2), plock(2), ptrace(2), semop(2), shmop(2), sig- 
nal (2), times (2), ulimit(2), umask(2), wait (2). 
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NAME 

getpid, getpgrp, getppid — get process, process group, and parent 
process IDs 

SYNOPSIS 

int getpid 0 

int getpgrp 0 

int getppid 0 

DESCRIPTION 

Getpid returns the process ID of the calling process. 

Getpgrp returns the process group ID of the calling process. 
Getppid returns the parent process ID of the calling process. 
SEE ALSO 

exec (2), fork (2), intro(2), setpgrp(2), signal (2). 
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NAME 

getuid, geteuid, getgid, getegid — get real user, effective user, real 
group, and effective group IDs 

SYNOPSIS 

unsigned short getuid 0 

unsigned short geteuid 0 

unsigned short getgid 0 

unsigned short getegid 0 

DESCRIPTION 

Getuid returns the real user ID of the calling process. 

Geteuid returns the effective user ID of the calling process. 
Getgid returns the real group ID of the calling process. 
Getegid returns the effective group ID of the calling process. 

SEE ALSO 

intro(2), setuid(2). 
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NAME 

ioctl — control device 

SYNOPSIS 

ioctl (fildes, request, arg) 
int fildes, request; 

DESCRIPTION 

Ioctl performs a variety of functions on character special files 
(devices). The write-ups of various devices in Section 7 of the 
UNIX Programmer's Manual —Volume 3: System Administration 
Facilities discuss how ioctl applies to them. 

Ioctl will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[ENOTTY] Fildes is not associated with a character special 



RETURN VALUE 

If an error has occurred, a value of —1 is returned and errno is set 
to indicate the error. 

SEE ALSO 

termio(7) in the UNIX Programmer's Manual —Volume 3: Sys- 
tem Administration Facilities. 



device. 



[EINVAL] 



Request or arg is not valid. See Section 7 of the 
UNIX Programmer's Manual— Volume 3: Sys- 
tem Administration Facilities. 



[EINTR] 



A signal was caught during the ioctl system call. 
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NAME 

kill — send a signal to a process or a group of processes 

SYNOPSIS 

int kill (pid, sig) 
int pid, sig; 

DESCRIPTION 

Kill sends a signal to a process or a group of processes. The pro- 
cess or group of processes to which the signal is to be sent is 
specified by pid. The signal that is to be sent is specified by sig 
and is either one from the list given in signal (2), or 0. If sig is 0 
(the null signal), error checking is performed but no signal is actu- 
ally sent. This can be used to check the validity of pid. 

The real or effective user ID of the sending process must match the 
real or effective user ID of the receiving process, unless the 
effective user ID of the sending process is super-user. 

The processes with a process ID of 0 and a process ID of 1 are spe- 
cial processes (see intro(2)) and will be referred to below as procO 
and prod , respectively. 

If pid is greater than zero, sig will be sent to the process whose 
process ID is equal to pid. Pid may equal 1. 

If pid is 0, sig will be sent to all processes excluding procO and 
prod whose process group ID is equal to the process group ID of 
the sender. 

If pid is —1 and the effective user ID of the sender is not super- 
user, sig will be sent to all processes excluding procO and prod 
whose real user ID is equal to the effective user ID of the sender. 

If pid is —1 and the effective user ID of the sender is super-user, 
sig will be sent to all processes excluding procO and prod. 

If pid is negative but not —1, sig will be sent to all processes 
whose process group ID is equal to the absolute value of pid. 

Kill will fail and no signal will be sent if one or more of the fol- 
lowing are true: 

[EINVAL] Sig is not a valid signal number. 

[EINVAL] Sig is SIGKILL and pid is 1 (procl). 

[ESRCH] No process can be found corresponding to that 

specified by pid. 
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[EPERM] The user ID of the sending process is not super- 
user, and its real or effective user ID does not 
match the real or effective user ID of the receiv- 
ing process. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of — 1 is returned and errno is set to indicate the error. 

SEE ALSO 

getpid (2) , setpgrp (2) , signal (2) . 

kill C 1 ) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
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NAME 

link — link to a file 

SYNOPSIS 

int link (pathl, path2) 
char *pathl, *path2; 

DESCRIPTION 

Pathl points to a path name naming an existing file. Path2 points 
to a path name naming the new directory entry to be created. 
Link creates a new link (directory entry) for the existing file. 

Link will fail and no link will be created if one or more of the fol- 
lowing are true: 

[ENOTDIR] A component of either path prefix is not a direc- 



[EPERM] 



[ENOENTl 



[EACCES] 



[EXDEV] 



[ENOENT] 



[EEXIST] 



tory. 

A component of either path prefix does not exist. 

A component of either path prefix denies search 
permission. 

The file named by pathl does not exist. 

The link named by path2 exists. 

The file named by pathl is a directory and the 
effective user ID is not super-user. 

The link named by path2 and the file named by 
pathl are on different logical devices (file sys- 
tems) . 



[ENOENT] 



Path2 points to a null path name. 

The requested link requires writing in a directory 
with a mode that denies write permission. 



[EACCES] 



[EROFS] 



The requested link requires writing in a directory 
on a read-only file system. 



[EFAULT] 



Path points outside the allocated address space of 
the process. 



[EMLINK] 



The maximum number of links to a file would be 
exceeded. 
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RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

unlink (2). 
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NAME 

lseek — move read/write file pointer 

SYNOPSIS 

long lseek (fildes, offset, whence) 
int fildes; 
long offset; 
int whence; 

DESCRIPTION 

Fildes is a file descriptor returned from a creat, open, dup, or 
fcntl system call. Lseek sets the file pointer associated with fildes 
as follows: 

If whence is 0, the pointer is set to offset bytes. 

If whence is 1, the pointer is set to its current location 
plus offset. 

If whence is 2, the pointer is set to the size of the file plus 
offset. 

Upon successful completion, the resulting pointer location, as 
measured in bytes from the beginning of the file, is returned. 

Lseek will fail and the file pointer will remain unchanged if one or 
more of the following are true: 

[EBADF] Fildes is not an open file descriptor. 

[ESPIPE] Fildes is associated with a pipe or fifo. 

[EINVAL and SIGSYS signal] 

Whence is not 0, 1, or 2. 

[EINVAL] The resulting file pointer would be negative. 

Some devices are incapable of seeking. The value of the file 
pointer associated with such a device is undefined. 

RETURN VALUE 

Upon successful completion, a non-negative integer indicating the 
file pointer value is returned. Otherwise, a value of —1 is returned 
and errno is set to indicate the error. 

SEE ALSO 

creat(2), dup (2), fcntl (2), open (2). 
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NAME 

mknod — make a directory, or a special or ordinary file 

SYNOPSIS 

int mknod (path, mode, dev) 
char *path; 
int mode, dev; 

DESCRIPTION 

Mknod creates a new file named by the path name pointed to by 
path. The mode of the new file is initialized from mode. Where 
the value of mode is interpreted as follows: 

0170000 file type; one of the following: 
0010000 fifo special 
0020000 character special 
0040000 directory 
0060000 block special 
0100000 or 0000000 ordinary file 
0004000 set user ID on execution 
0002000 set group ID on execution 
0001000 save text image after execution 
0000777 access permissions; constructed from the follow- 
ing 

0000400 read by owner 
0000200 write by owner 

0000100 execute (search on directory) by owner 
0000070 read, write, execute (search) by group 
0000007 read, write, execute (search) by others 

The owner ID of the file is set to the effective user ID of the pro- 
cess. The group ID of the file is set to the effective group ID of the 
process. 

Values of mode other than those above are undefined and should 
not be used. The low-order 9 bits of mode are modified by the 
process's file mode creation mask: all bits set in the process's file 
mode creation mask are cleared. See umask(2). If mode indi- 
cates a block or character special file, dev is a configuration- 
dependent specification of a character or block I/O device. If 
mode does not indicate a block special or character special device, 
dev is ignored. 

Mknod may be invoked only by the super-user for file types other 
than FIFO special. 
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Mknod will fail and the new file will not be created if one or more 
of the following are true: 

[EPERM] The effective user ID of the process is not super- 

user. 

1ENOTDIR] A component of the path prefix is not a directory. 

[ENOENTl A component of the path prefix does not exist. 

lEROFSl The directory in which the file is to be created is 

located on a read-only file system. 

[EEXISTl The named file exists. 

[EFAULTl Path points outside the allocated address space of 
the process. 

RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

chmod(2), exec (2), umask(2), fs(4). 

mkdir(l) in the UNIX Programmer's Manual —Volume I: Com- 
mands and Utilities. 
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NAME 

mount — mount a file system 

SYNOPSIS 

int mount (spec, dir, rwflag) 
char *spec, *dir; 
int rwflag; 

DESCRIPTION 

Mount requests that a removable file system contained on the 
block special file identified by spec be mounted on the directory 
identified by dir. Spec and dir are pointers to path names. 

Upon successful completion, references to the file dir will refer to 
the root directory on the mounted file system. 

The low-order bit of rwflag is used to control write permission on 
the mounted file system; if 1, writing is forbidden, otherwise writ- 
ing is permitted according to individual file accessibility. 

Mount may be invoked only by the super-user. 

Mount will fail if one or more of the following are true: 

[EPERM] The effective user ID is not super-user. 

[ENOENT] Any of the named files does not exist. 

[ENOTDIR] A component of a path prefix is not a directory. 

[ENOTBLK] Spec is not a block special device. 

[ENXIO] The device associated with spec does not exist. 

[ENOTDIR] Dir is not a directory. 

[EFAULT] Spec or dir points outside the allocated address 

space of the process. 

[EBUSY] Dir is currently mounted on, is someone's current 

working directory, or is otherwise busy. 

[EBUSYl The device associated with spec is currently 

mounted. 

[EBUSYl There are no more mount table entries. 

RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

umount(2). 
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NAME 

msgctl — message control operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/msg.h> 

int msgctl (msqid, cmd, buf) 
int msqid, cmd; 
struct msqidds *buf; 

DESCRIPTION 

Msgctl provides a variety of message control operations as 
specified by cmd. The following cmds are available: 

IPCJSTAT Place the current value of each member of the 

data structure associated with msqid into the 
structure pointed to by buf. The contents of this 
structure are defined in intro (2) . {READ} 

IPCJSET Set the value of the following members of the 

data structure associated with msqid to the 
corresponding value found in the structure 
pointed to by buf : 

msg_perm.uid 

msg_perm.gid 

msg_perm.mode /* only low 9 bits */ 
msgqbytes 

This cmd can only be executed by a process that 
has an effective user ID equal to either that of 
super user or to the value of msg_perm.uid in the 
data structure associated with msqid. Only 
super user can raise the value of msg qbytes. 

IPC_RMID Remove the message queue identifier specified by 
msqid from the system and destroy the message 
queue and data structure associated with it. This 
cmd can only be executed by a process that has 
an effective user ID equal to either that of super 
user or to the value of msgjperm.uid in the data 
structure associated with msqid. 

Msgctl will fail if one or more of the following are true: 

[EINVAL] Msqid is not a valid message queue identifier. 
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[EINVAL] Cmd is not a valid command. 

[EACCES] Cmd is equal to IPCJSTAT and {READ} operation 

permission is denied to the calling process (see 
introi.2)). 

[EPERMl Cmd is equal to IPC_RMID or IPC_SET. The 

effective user ID of the calling process is not 
equal to that of super user and it is not equal to 
the value of msg_perm.uid in the data structure 
associated with msqid. 

[EPERMl Cmd is equal to IPCJSET, an attempt is being 

made to increase to the value of msg_qbytes, and 
the effective user ID of the calling process is not 
equal to that of super user. 

[EFAULT] Buf points to an illegal address. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

intro(2), msgget(2), msgop(2). 
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NAME 

msgget — get message queue 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/msg.h> 

int msgget (key, msgflg) 
keyj key; 
int msgflg; 

DESCRIPTION 

Msgget returns the message queue identifier associated with key . 

A message queue identifier and associated message queue and data 
structure (see introil)) are created for key if one of the following 
are true: 

10 Key is equal to IPC_PRIVATE. 

Key does not already have a message queue identifier asso- 
ciated with it, and {msgflg & IPC_CREAT) is "true". 

Upon creation, the data structure associated with the new message 
queue identifier is initialized as follows: 

Msg_perm.cuid, msgjperm.uid, msg_perm.cgid, and 
msg_perm.gid are set equal to the effective user ID and 
effective group ID, respectively, of the calling process. 

The low-order 9 bits of msg_perm.mode are set equal to 
the low-order 9 bits of msgflg. 

Msg_qnum, msglspid, msgjrpid, msgstime, and 
msgjrtime are set equal to 0. 

Msg_ctime is set equal to the current time. 

Msgjqbytes is set equal to the system limit. 

Msgget will fail if one or more of the following are true: 

[EACCES] A message queue identifier exists for key, but 

operation permission (see introil)) as specified 
by the low-order 9 bits of msgflg would not be 
granted. 

[ENOENTl A message queue identifier does not exist for key 
and {msgflg & IPC_CREAT) is "false". 
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[ENOSPC] 



A message queue identifier is to be created but 
the system-imposed limit on the maximum 
number of allowed message queue identifiers sys- 
tem wide would be exceeded. 



[EEXIST] 



A message queue identifier exists for key but 
((msgflg& IPC_CREAT) & msgflg & 
IPC_EXCL)) is "true". 



RETURN VALUE 

Upon successful completion, a non-negative integer, namely a mes- 
sage queue identifier, is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

intro(2), msgctl(2), msgop(2). 
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NAME 



msgop — message operations 



SYNOPSIS 



#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/msg.h> 

int msgsnd (msqid, msgp, msgsz, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz, msgflg; 

int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz; 
long msgtyp; 
int msgflg; 



Msgsnd is used to send a message to the queue associated with the 
message queue identifier specified by msqid. {WRITE} Msgp 
points to a structure containing the message. This structure is 
composed of the following members: 



Mtype is a positive integer that can be used by the receiving pro- 
cess for message selection (see msgrcv below,) . Mtext is any text 
of length msgsz bytes. Msgsz can range from 0 to a system- 
imposed maximum. 

Msgflg specifies the action to be taken if one or more of the fol- 
lowing are true: 

The number of bytes already on the queue is equal to 
msg qbytes (see intro(2)). 

The total number of messages on all queues system-wide is 
equal to the system-imposed limit. 

These actions are as follows: 

If (msgflg & IPC_NOWAIT) is "true", the message will 
not be sent and the calling process will return immedi- 
ately. 



DESCRIPTION 



long 
char 



mtype; 
mtext[]; 



/* message type */ 
/* message text */ 
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If (msgflg & IPCJSfOWAIT) is "false", the calling process 
will suspend execution until one of the following occurs: 

The condition responsible for the suspension no 
longer exists, in which case the message is sent. 

Msqid is removed from the system (see 
msgctlil)). When this occurs, errno is set equal 
to EIDRM, and a value of —1 is returned. 

The calling process receives a signal that is to be 
caught. In this case the message is not sent and 
the calling process resumes execution in the 
manner prescribed in signal (2)). 

Msgsnd will fail and no message will be sent if one or more of the 
following are true: 

[EINVALl Msqid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling pro- 
cess (see introil)). 

[EINVALl Mtype is less than 1. 

[EAGAIN] The message cannot be sent for one of the rea- 
sons cited above and (msgfig & IPC_NOWAIT) is 
"true". 

[EINVALl Msgsz is less than zero or greater than the 

system-imposed limit. 

[EFAULT] Msgp points to an illegal address. 

Upon successful completion, the following actions are taken with 
respect to the data structure associated with msqid (see intro (2)). 

Msgjqnum is incremented by 1 . 

Msgjspid is set equal to the process ID of the calling pro- 
cess. 

Msgjstime is set equal to the current time. 

Msgrcv reads a message from the queue associated with the mes- 
sage queue identifier specified by msqid and places it in the struc- 
ture pointed to by msgp. {READ} This structure is composed of 
the following members: 

long mtype; /* message type */ 
char mtext[]; /* message text */ 
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Mtype is the received message's type as specified by the sending 
process. Mtext is the text of the message. Msgsz specifies the size 
in bytes of mtext. The received message is truncated to msgsz 
bytes if it is larger than msgsz and (msgflg & MSG_NOERROR) is 
"true". The truncated part of the message is lost and no indica- 
tion of the truncation is given to the calling process. 

Msgtyp specifies the type of message requested as follows: 

If msgtyp is equal to 0, the first message on the queue is 
received. 

If msgtyp is greater than 0, the first message of type 
msgtyp is received. 

If msgtyp is less than 0, the first message of the lowest 
type that is less than or equal to the absolute value of 
msgtyp is received. 

Msgflg specifies the action to be taken if a message of the desired 
type is not on the queue. These are as follows: 

If (msgflg & IPC_NOWAIT) is "true", the calling process 
will return immediately with a return value of —1 and 
errno set to ENOMSG. 

If (msgflg & IPCJSfOWAIT) is "false", the calling process 
will suspend execution until one of the following occurs: 

A message of the desired type is placed on the 
queue. 

Msqid is removed from the system. When this 
occurs, errno is set equal to EIDRM, and a value 
of —1 is returned. 

The calling process receives a signal that is to be 
caught. In this case a message is not received 
and the calling process resumes execution in the 
manner prescribed in signal (2)). 

Msgrcv will fail and no message will be received if one or more of 
the following are true: 

[EINVALl Msqid is not a valid message queue identifier. 

[EACCESl Operation permission is denied to the calling pro- 
cess. 

[EINVALl Msgsz is less than 0. 
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[E2BIG] Mtext is greater than msgsz and (msgflg & 

MSG NOERROR) is "false". 

[ENOMSG] The queue does not contain a message of the 
desired type and (msgtyp & IPCJNOWAIT) is 
"true". 

[EFAULT] Msgp points to an illegal address. 

Upon successful completion, the following actions are taken with 
respect to the data structure associated with msqid (see intro (2)). 

Msg_qnum is decremented by 1 . 

Msgjrpid is set equal to the process ID of the calling pro- 
cess. 

Msg_rtime is set equal to the current time. 

RETURN VALUES 

If msgsnd or msgrcv return due to the receipt of a signal, a value 
of —1 is returned to the calling process and errno is set to EINTR. 
If they return due to removal of msqid from the system, a value of 
—1 is returned and errno is set to EIDRM. 

Upon successful completion, the return value is as follows: 

Msgsnd returns a value of 0. 

Msgrcv returns a value equal to the number of bytes actu- 
ally placed into mtext. 

Otherwise, a value of —1 is returned and errno is set to indicate 
the error. 

SEE ALSO 

intro (2), msgctl(2), msgget(2), signal (2). 
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NAME 

nice — change priority of a process 

SYNOPSIS 

int nice (incr) 
int incr; 

DESCRIPTION 

Nice adds the value of incr to the nice value of the calling process. 
A process's nice value is a positive number for which a more posi- 
tive value results in lower CPU priority. 

A maximum nice value of 39 and a minimum nice value of 0 are 
imposed by the system. Requests for values above or below these 
limits result in the nice value being set to the corresponding limit. 

[EPERM] Nice will fail and not change the nice value if 

incr is negative or greater than 40 and the 
effective user ID of the calling process is not 
super-user. 

RETURN VALUE 

Upon successful completion, nice returns the new nice value minus 
20. Otherwise, a value of —1 is returned and errno is set to indi- 
cate the error. 

SEE ALSO 

exec (2). 

nice(l) in the UNIX Programmer's Manual— Volume 1: Com- 
mands and Utilities. 
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NAME 

open — open for reading or writing 

SYNOPSIS 

#include <fcntl.h> 

int open (path, oflag [ , mode ] ) 

char *path; 

int oflag, mode; 

DESCRIPTION 

Path points to a path name naming a file. Open opens a file 
descriptor for the named file and sets the file status flags according 
to the value of oflag. Oflag values are constructed by or-ing flags 
from the following list (only one of the first three flags below may 
be used): 

0_RDONLY Open for reading only. 

0_WRONLY Open for writing only. 

O RDWR Open for reading and writing. 

ONDELAY This flag may affect subsequent reads and writes. 
See read (2) and write (2) . 

FIFO 



When opening a 
0_WRONLY set: 

If O NDELAY is set: 



with O RDONLY or 



An open for reading-only will return 
without delay. An open for writing-only 
will return an error if no process currently 
has the file open for reading. 

If O NDELAY is clear: 

An open for reading-only will block until a 
process opens the file for writing. An open 
for writing-only will block until a process 
opens the file for reading. 

When opening a file associated with a communica- 
tion line: 

If O NDELAY is set: 

The open will return without waiting for 
carrier. 
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If ONDELAY is clear: 

The open will block until carrier is present. 

0_APPEND If set, the file pointer will be set to the end of the 
file prior to each write. 

0_CREAT If the file exists, this flag has no effect. Otherwise, 
the owner ID of the file is set to the effective user ID 
of the process, the group ID of the file is set to the 
effective group ID of the process, and the low-order 
12 bits of the file mode are set to the value of mode 
modified as follows (see creatil)): 

All bits set in the file mode creation mask 
of the process are cleared. See umask (2) . 

The "save text image after execution bit" 
of the mode is cleared. See chmodil). 

0_TRUNC If the file exists, its length is truncated to 0 and the 
mode and owner are unchanged. 

0_EXCL If 0_EXCL and OCREAT are set, open will fail if 
the file exists. 

The file pointer used to mark the current position within the file is 
set to the beginning of the file. 

The new file descriptor is set to remain open across exec system 
calls. See fcntl (2). 

The named file is opened unless one or more of the following are 
true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] O CREAT is not set and the named file does not 
exist. 

[EACCES] A component of the path prefix denies search 
permission. 

[EACCES] Oflag permission is denied for the named file. 

[EISDIR] The named file is a directory and oflag is write 

or read/write. 

[EROFS] The named file resides on a read-only file system 

and oflag is write or read/ write. 
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[EMFILE] 
[ENXIO] 

[ETXTBSY] 

[EFAULT] 
[EEXIST] 
[ENXIO] 



Twenty (20) file descriptors are currently open. 

The named file is a character special or block 
special file, and the device associated with this 
special file does not exist. 

The file is a pure procedure (shared text) file 
that is being executed and oflag is write or 
read/ write. 

Path points outside the allocated address space of 
the process. 

0_CREAT and 0_EXCL are set, and the named 
file exists. 



O NDELAY is set, the named file is a FIFO, 
0_WRONLY is set, and no process has the file 
open for reading. 

[EINTR] A signal was caught during the open system call. 

[ENFILE] The system file table is full. 

RETURN VALUE 

Upon successful completion, the file descriptor is returned. Other- 
wise, a value of —1 is returned and errno is set to indicate the 
error. 

SEE ALSO 

chmod(2), close(2), creat(2), dup(2), fcntl(2), lseek(2), read(2), 
umask(2), write (2). 
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NAME 

pause — suspend process until signal 

SYNOPSIS 

pause 0 

DESCRIPTION 

Pause suspends the calling process until it receives a signal. The 
signal must be one that is not currently set to be ignored by the 
calling process. 

If the signal causes termination of the calling process, pause will 
not return. 

If the signal is caught by the calling process and control is 
returned from the signal-catching function (see signal (2)), the cal- 
ling process resumes execution from the point of suspension; with a 
return value of —1 from pause and errno set to EINTR. 

SEE ALSO 

alarm (2), kill (2), signal (2), wait (2). 
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NAME 

pipe — create an interprocess channel 

SYNOPSIS 

int pipe (fildes) 
int fildes[2l; 

DESCRIPTION 

Pipe creates an I/O mechanism called a pipe and returns two file 
descriptors, fildes[0] and fildesll]. FildeslO] is opened for read- 
ing and fildesll] is opened for writing. 

Up to 5120 bytes of data are buffered by the pipe before the writ- 
ing process is blocked. A read only file descriptor fildeslO] 
accesses the data written to fildesll] on a first-in-first-out (FIFO) 
basis. 



[EMFILE] Pipe will fail if 19 or more file descriptors are 

currently open. 

[ENFILE] The system file table is full. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

read (2), write (2). 

sh(l) in the UNIX Programmer's Manual —Volume 1: Commands 
and Utilities. 
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NAME 



plock — lock process, text, or data in memory 



SYNOPSIS 



#include <sys/lock.h> 

int plock (op) 
int op; 



DESCRIPTION 



Plock allows the calling process to lock its text segment (text 
lock), its data segment (data lock), or both its text and data seg- 
ments (process lock) into memory. Locked segments are immune 
to all routine swapping. Plock also allows these segments to be 
unlocked. The effective user ID of the calling process must be 
super-user to use this call. Op specifies the following: 



PROCLOCK - lock text and data segments into memory 



TXTLOCK - lock text segment into memory (text 



DATLOCK - lock data segment into memory (data 



UNLOCK - remove locks 

Plock will fail and not perform the requested operation if one or 
more of the following are true: 



(process lock) 



lock) 



lock) 



[EPERM] 



The effective user ID of the calling process is not 
super-user. 



[EINVAL] 



Op is equal to PROCLOCK and a process lock, a 
text lock, or a data lock already exists on the cal- 
ling process. 



[EINVALl 



Op is equal to TXTLOCK and a text lock, or a 
process lock already exists on the calling process. 

Op is equal to DATLOCK and a data lock, or a 
process lock already exists on the calling process. 

Op is equal to UNLOCK and no type of lock 
exists on the calling process. 



[EINVAL] 



[EINVAL] 
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RETURN VALUE 

Upon successful completion, a value of 0 is returned to the calling 
process. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 

SEE ALSO 

exec (2), exit (2), fork (2). 
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NAME 

profil — execution time profile 

SYNOPSIS 

void profil (buff, bufsiz, offset, scale) 
char *buff; 

int bufsiz, offset, scale; 
DESCRIPTION 

Buff points to an area of core whose length (in bytes) is given by 
bufsiz. After this call, the user's program counter (pc) is exam- 
ined each clock tick (60th second); offset is subtracted from it, 
and the result multiplied by scale. If the resulting number 
corresponds to a word inside buff, that word is incremented. 

The scale is interpreted as an unsigned, fixed-point fraction with 
binary point at the left: 0177777 (octal) gives a 1-1 mapping of 
pc's to words in buff; 011111 (octal) maps each pair of instruction 
words together. 02 (octal) maps all instructions onto the beginning 
of buff (producing a non-interrupting core clock) . 

Profiling is turned off by giving a scale of 0 or 1. It is rendered 
ineffective by giving a bufsiz of 0. Profiling is turned off when an 
exec is executed, but remains on in child and parent both after a 
fork. Profiling will be turned off if an update in buff would cause 
a memory fault. 

RETURN VALUE 

Not defined. 

SEE ALSO 

monitor (3C). 

prof(l) in the UNIX Programmer's Manual— Volume 1: Com- 
mands and Utilities. 
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NAME 

ptrace — process trace 

SYNOPSIS 

int ptrace (request, pid, addr, data); 
int request, pid, addr, data; 

DESCRIPTION 

Ptrace provides a means by which a parent process may control 
the execution of a child process. Its primary use is for the imple- 
mentation of breakpoint debugging; see sdb(l). The child process 
behaves normally until it encounters a signal (see signal (2) for the 
list) , at which time it enters a stopped state and its parent is 
notified via wait (2). When the child is in the stopped state, its 
parent can examine and modify its "core image" using ptrace. 
Also, the parent can cause the child either to terminate or con- 
tinue, with the possibility of ignoring the signal that caused it to 
stop. 

The request argument determines the precise action to be taken by 
ptrace and is one of the following: 

0 This request must be issued by the child process if it 
is to be traced by its parent. It turns on the child's 
trace flag that stipulates that the child should be left 
in a stopped state upon receipt of a signal rather 
than the state specified by func; see signal (2). The 
pid, addr, and data arguments are ignored, and a 
return value is not defined for this request. Peculiar 
results will ensue if the parent does not expect to 
trace the child. 

The remainder of the requests can only be used by the parent pro- 
cess. For each, pid is the process ID of the child. The child must 
be in a stopped state before these requests are made. 

1, 2 With these requests, the word at location addr in 
the address space of the child is returned to the 
parent process. If I and D space are separated (as 
on some computers), request 1 returns a word from I 
space, and request 2 returns a word from D space. 
If I and D space are not separated (as on the 3B20 
computer and some other computers), either request 
1 or request 2 may be used with equal results. The 
data argument is ignored. These two requests will 
fail if addr is not the start address of a word, in 
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which case a value of —1 is returned to the parent 
process and the parent's errno is set to EIO. 

3 With this request, the word at location addr in the 
child's USER area in the system's address space (see 
<sys/user.h>) is returned to the parent process. 
Addresses in this area generally range from 0 to 
2048 on the 3B20 computer and others. The data 
argument is ignored. This request will fail if addr is 
not the start address of a word or is outside the 
USER area, in which case a value of —1 is returned 
to the parent process and the parent's errno is set to 
EIO. 

With these requests, the value given by the data 
argument is written into the address space of the 
child at location addr. If I and D space are 
separated (as on some computers) request 4 writes a 
word into I space, and request 5 writes a word into 
D space. If I and D space are not separated (as on 
the 3B20 computer and others), either request 4 or 
request 5 may be used with equal results. Upon suc- 
cessful completion, the value written into the address 
space of the child is returned to the parent. These 
two requests will fail if addr is a location in a pure 
procedure space and another process is executing in 
that space, or addr is not the start address of a 
word. Upon failure a value of —1 is returned to the 
parent process and the parent's errno is set to EIO. 

With this request, a few entries in the child's USER 
area can be written. Data gives the value that is to 
be written and addr is the location of the entry. 
The few entries that can be written are: 

the general registers (i.e., registers 0—11 on 
the 3B20 computer, registers 0—7 on some 
others, and registers 0—15 on some other 
machines) 

the condition codes of the Processor Status 
Word on the 3B20 computer 

the floating point status register and six 
floating point registers on some computers 
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certain bits of the Processor Status Word on 
some computers (i.e, bits 0—4 and 8—11) 

certain bits of the Processor Status Long- 
word on the some computers (i.e., bits 0—7, 
16-20, and 30-31). 

7 This request causes the child to resume execution. 
If the data argument is 0, all pending signals includ- 
ing the one that caused the child to stop are can- 
celed before it resumes execution. If the data argu- 
ment is a valid signal number, the child resumes 
execution as if it had incurred that signal, and any 
other pending signals are canceled. The addr argu- 
ment must be equal to 1 for this request. Upon suc- 
cessful completion, the value of data is returned to 
the parent. This request will fail if data is not 0 or 
a valid signal number, in which case a value of —1 is 
returned to the parent process and the parent's errno 
is set to EIO. 

8 This request causes the child to terminate with the 
same consequences as exit (2) . 

9 This request sets the trace bit in the Processor 
Status Word of the child (i.e., bit 4 on some com- 
puters) and then executes the same steps as listed 
above for request 7. The trace bit causes an inter- 
rupt upon completion of one machine instruction. 
This effectively allows single stepping of the child. 
On the 3B20 computer, there is no trace bit; and this 
request returns an error. 

To forestall possible fraud, ptrace inhibits the set-user-id facility 
on subsequent exec (2) calls. If a traced process calls exec, it will 
stop before executing the first instruction of the new image show- 
ing signal SIGTRAP. 

GENERAL ERRORS 

Ptrace will in general fail if one or more of the following are true: 

[EIO] Request is an illegal number. 

[ESRCH] Pid identifies a child that does not exist or has 

not executed a ptrace with request 0. 
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SEE ALSO 

exec (2), signal (2), wait (2). 

sdb(l) in the UNIX Programmer's Manual —Volume I: Com- 
mands and Utilities. 



UNIX Programmer s Manual 



System Calls and Library Routines— 71 



READ (2) 



READ (2) 



NAME 

read — read from file 

SYNOPSIS 

int read (tildes, buf, nbyte) 
int tildes; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup,fcntl, 
or pipe system call. 

Read attempts to read nbyte bytes from the file associated with 
fildes into the buffer pointed to by buf. 

On devices capable of seeking, the read starts at a position in the 
file given by the file pointer associated with fildes. Upon return 
from read, the file pointer is incremented by the number of bytes 
actually read. 

Devices that are incapable of seeking always read from the current 
position. The value of a file pointer associated with such a file is 
undefined. 

Upon successful completion, read returns the number of bytes 
actually read and placed in the buffer; this number may be less 
than nbyte if the file is associated with a communication line (see 
ioctl(2) and termioil)), or if the number of bytes left in the file is 
less than nbyte bytes. A value of 0 is returned when an end-of-file 
has been reached. 

When attempting to read from an empty pipe (or FIFO) : 

If ONDELAY is set, the read will return a 0. 

If O NDELAY is clear, the read will block until data is 
written to the file or the file is no longer open for writing. 

When attempting to read a file associated with a tty that has no 
data currently available: 

If O NDELAY is set, the read will return a 0. 

If O NDELAY is clear, the read will block until data 
becomes available. 
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Read will fail if one or more of the following are true: 



[EBADFl 



Fildes is not a valid file descriptor open for read- 
ing. 

Buf points outside the allocated address space. 
A signal was caught during the read system call. 



[EFAULTl 



[EINTR] 



RETURN VALUE 

Upon successful completion a non-negative integer is returned indi- 
cating the number of bytes actually read. Otherwise, a —1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

creat(2), dup(2), fcntl(2), ioctl(2), open (2), pipe (2). 
termio(7) in the UNIX Programmer's Manual— Volume 3: Sys- 
tem Administration Facilities. 
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NAME 

semctl — semaphore control operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/sem.h> 

int semctl (semid, semnum, cmd, arg) 
int semid, cmd; 
int semnum; 
union semun { 
int val; 

struct semid ds *buf; 
ushort *array; 

} arg; 
DESCRIPTION 

Semctl provides a variety of semaphore control operations as 
specified by cmd. 

The following cmds are executed with respect to the semaphore 
specified by semid and semnum: 

GETVAL Return the value of semval (see introil)). 
{READ} 

SETVAL Set the value of semval to arg.val. {ALTER} 
When this cmd is successfully executed, the 
semadj value corresponding to the specified 
semaphore in all processes is cleared. 

GETPID Return the value of sempid. {READ} 

GETNCNT Return the value of semncnt. {READ} 

GETZCNT Return the value of semzcnt. {READ} 

The following cmds return and set, respectively, every semval in 
the set of semaphores. 

GETALL Place semvals into array pointed to by 
arg.array. {READ} 

SETALL Set semvals according to the array pointed 
to by arg.array. {ALTER} When this cmd is 
successfully executed the semadj values 
corresponding to each specified semaphore in 
all processes are cleared. 
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The following cmds are also available: 

IPC STAT Place the current value of each member of 
the data structure associated with semid into 
the structure pointed to by arg.buf. The 
contents of this structure are denned in 
intro(2). {READ} 

IPC SET Set the value of the following members of 
the data structure associated with semid to 
the corresponding value found in the struc- 
ture pointed to by arg.buf : 
semjperm.uid 
sem_perm.gid 

sem_perm.mode /* only low 9 bits */ 

This cmd can only be executed by a process 
that has an effective user ID equal to either 
that of super-user or to the value of 
semjperm.uid in the data structure associ- 
ated with semid. 

IPC RMID Remove the semaphore identifier specified 
by semid from the system and destroy the 
set of semaphores and data structure associ- 
ated with it. This cmd can only be executed 
by a process that has an effective user ID 
equal to either that of super-user or to the 
value of semjperm.uid in the data structure 
associated with semid. 

Semctl will fail if one or more of the following are true: 

[EINVALl Semid is not a valid semaphore 

identifier. 

[EINVALl Semnum is less than zero or greater than 
sem nsems. 

[EINVALl Cmd is not a valid command. 

[EACCES] Operation permission is denied to the 
calling process (see intro(2)). 

[ERANGE] Cmd is SETVAL or SETALL and the 
value to which semval is to be set is 
greater than the system imposed max- 
imum. 
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[EPERM] Cmd is equal to IPC_RMID or IPCJSET 

and the effective user ID of the calling 
process is not equal to that of super-user 
and it is not equal to the value of 
semjperm.uid in the data structure asso- 
ciated with semid. 

[EFAULT] Arg.buf points to an illegal address. 

RETURN VALUE 

Upon successful completion, the value returned depends on cmd as 
follows: 

The value of semval. 
The value of sempid. 
The value of semncnt. 
The value of semzcnt. 
A value of 0. 
1 is returned and errno is set to indicate 



GETVAL 
GETPID 
GETNCNT 
GETZCNT 
All others 

Otherwise, a value of 

the error. 



SEE ALSO 

intro(2), semget(2), semop(2). 
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NAME 

semget — get set of semaphores 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

int semget (key, nsems, semflg) 

key_t key; 

int nsems, semflg; 

DESCRIPTION 

Semget returns the semaphore identifier associated with key. 

A semaphore identifier and associated data structure and set con- 
taining nsems semaphores (see intro(2)) are created for key if one 
of the following are true: 

Key is equal to IPC_PRIVATE. 

Key does not already have a semaphore identifier associ- 
ated with it, and (semflg & IPC_CREAT) is "true". 

Upon creation, the data structure associated with the new sema- 
phore identifier is initialized as follows: 

Semjperm.cuid, semjperm.uid, semjperm.cgid, and 
sem_perm.gid are set equal to the effective user ID and 
effective group ID, respectively, of the calling process. 

The low-order 9 bits of sem_perm.mode are set equal to 
the low-order 9 bits of semflg. 

Semjnsems is set equal to the value of nsems. 

Sem_otime is set equal to 0 and sem_ctime is set equal to 
the current time. 

Semget will fail if one or more of the following are true: 

[EINVAL] Nsems is either less than or equal to zero or 

greater than the system-imposed limit. 

[EACCESl A semaphore identifier exists for key, but opera- 
tion permission (see introil)) as specified by the 
low-order 9 bits of semflg would not be granted. 

[EINVAL] A semaphore identifier exists for key, but the 

number of semaphores in the set associated with 
it is less than nsems and nsems is not equal to 
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zero. 

[ENOENT] A semaphore identifier does not exist for key and 
Uemflg & IPCjCREAT) is "false". 

[ENOSPC] A semaphore identifier is to be created but the 
system-imposed limit on the maximum number of 
allowed semaphore identifiers system wide would 
be exceeded. 

[ENOSPC] A semaphore identifier is to be created but the 
system-imposed limit on the maximum number of 
allowed semaphores system wide would be 
exceeded. 

[EEXIST] A semaphore identifier exists for key but ( 

Uemflg & IPC_CREAT) and ( semflg & 
IPC_EXCL) ) is "true". 

RETURN VALUE 

Upon successful completion, a non-negative integer, namely a 
semaphore identifier, is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

intro(2), semctl(2), semop(2). 
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NAME 

semop — semaphore operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/sem.h> 

int semop (semid, sops, nsops) 
int semid; 

struct sembuf **sops; 
int nsops; 

DESCRIPTION 

Semop is used to automatically perform an array of semaphore 
operations on the set of semaphores associated with the semaphore 
identifier specified by semid. Sops is a pointer to the array of 
semaphore-operation structures. Nsops is the number of such 
structures in the array. The contents of each structure includes 
the following members: 

short semjium; /* semaphore number */ 
short sem_op; /* semaphore operation */ 
short semjlg; /* operation flags */ 

Each semaphore operation specified by sem op is performed on the 
corresponding semaphore specified by semid and sem num. 

Sem op specifies one of three semaphore operations as follows: 

If sem_op is a negative integer, one of the following will 
occur: {ALTER} 

If semval (see intro{2)) is greater than or equal 
to the absolute value of sem op, the absolute 
value of sem op is subtracted from semval. Also, 
if (sem Jig & SEMJJNDO) is "true", the abso- 
lute value of sem_op is added to the calling 
process's semadj value (see exit (2)) for the 
specified semaphore. 

If semval is less than the absolute value of 
sem_op and (sem Jig & IPC_NOWAIT) is "true", 
semop will return immediately. 

If semval is less than the absolute value of 
semop and (sem Jig & IPC_NOWAIT) is 
"false", semop will increment the semncnt 
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associated with the specified semaphore and 
suspend execution of the calling process until one 
of the following conditions occur. 

Semval becomes greater than or equal to the 
absolute value of semop. When this occurs, 
the value of semncnt associated with the 
specified semaphore is decremented, the absolute 
value of sem_op is subtracted from semval and, 
if (sent Jig & SEMJJNDO) is "true", the abso- 
lute value of sem_op is added to the calling 
process's semadj value for the specified sema- 
phore. 

The semid for which the calling process is 
awaiting action is removed from the system (see 
semctKD). When this occurs, errno is set 
equal to EIDRM, and a value of —1 is returned. 

The calling process receives a signal that is to 
be caught. When this occurs, the value of 
semncnt . associated with the specified semaphore 
is decremented, and the calling process resumes 
execution in the manner prescribed in signal (2) . 

If sem_op is a positive integer, the value of sem op is 
added to semval and, if (sem Jig & SEMJJNDO) is 
"true", the value of sem op is subtracted from the calling 
process's semadj value for the specified semaphore. 
{ALTER} 

If sem_pp is zero, one of the following will occur: 
{READ} 

If semval is zero, semop will return immediately. 

If semval is not equal to zero and (sem Jig & 
IPC_NOWATT) is "true", semop will return 
immediately. 

If semval is not equal to zero and (sem Jig & 
IPC_NOWATT) is "false", semop will increment 
the semzcnt associated with the specified sema- 
phore and suspend execution of the calling pro- 
cess until one of the following occurs: 
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Semval becomes zero, at which time the value 
of semzcnt associated with the specified sema- 
phore is decremented. 

The semid for which the calling process is 
awaiting action is removed from the system. 
When this occurs, errno is set equal to EIDRM, 
and a value of —1 is returned. 

The calling process receives a signal that is to 
be caught. When this occurs, the value of 
semzcnt associated with the specified semaphore 
is decremented, and the calling process resumes 
execution in the manner prescribed in signal (2). 

Semop will fail if one or more of the following are true for any of 
the semaphore operations specified by sops: 

[EINVAL] Semid is not a valid semaphore identifier. 

[EFBIG] Semjium is less than zero or greater than or 

equal to the number of semaphores in the set 
associated with semid. 

[E2BIG] Nsops is greater than the system-imposed max- 

imum. 

[EACCES] Operation permission is denied to the calling pro- 
cess (see introil)). 

[EAGAIN] The operation would result in suspension of the 

calling process but (sem Jig & IPC_NOWAIT) is 
"true". 

[ENOSPC] The limit on the number of individual processes 
requesting an SEMJJNDO would be exceeded. 

[EINVAL] The number of individual semaphores for which 

the calling process requests a SEMJJNDO would 
exceed the limit. 

[ERANGE] An operation would cause a semval to overflow 
the system-imposed limit. 

[ERANGE] An operation would cause a semadj value to 
overflow the system-imposed limit. 

[EFAULT] Sops points to an illegal address. 
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Upon successful completion, the value of sempid 
for each semaphore specified in the array pointed 
to by sops is set equal to the process ID of the 
calling process. 

RETURN VALUE 

If semop returns due to the receipt of a signal, a value of —1 is 
returned to the calling process and errno is set to EINTR. If it 
returns due to the removal of a semid from the system, a value of 
—1 is returned and errno is set to EIDRM. 

Upon successful completion, the value of semval at the time of the 
call for the last operation in the array pointed to by sops is 
returned. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), semctl(2), semget(2). 
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NAME 

setpgrp — set process group ID 

SYNOPSIS 

int setpgrp 0 

DESCRIPTION 

Setpgrp sets the process group ID of the calling process to the pro- 
cess ID of the calling process and returns the new process group 
ID. 

RETURN VALUE 

Setpgrp returns the value of the new process group ID. 

SEE ALSO 

exec (2), fork (2), getpid(2), intro(2), kill (2), signal (2). 
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NAME 

setuid, setgid — set user and group IDs 

SYNOPSIS 

int setuid (uid) 
int uid; 

int setgid (gid) 
int gid; 

DESCRIPTION 

Setuid {setgid) is used to set the real user (group) ID and 
effective user (group) ID of the calling process. 

If the effective user ID of the calling process is super-user, the real 
user (group) ID and effective user (group) ID are set to uid (gid). 

If the effective user ID of the calling process is not super-user, but 
its real user (group) ID is equal to uid (gid), the effective user 
(group) ID is set to uid (gid). 

If the effective user ID of the calling process is not super-user, but 
the saved set-user (group) ID from exec (2) is equal to uid (gid), 
the effective user (group) ID is set to uid (gid). 

Setuid (setgid) will fail if the real user (group) ID of the calling 
process is not equal to uid (gid) and its effective user ID is not 
super-user. [EPERM] 

The uid is out of range. [EINVAL] 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

getuid(2), intro(2). 
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NAME 

shmctl — shared memory control operations 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/shm.h> 

int shmctl (shmid, cmd, buf) 
int shmid, cmd; 
struct shmidds *buf; 

DESCRIPTION 

Shmctl provides a variety of shared memory control operations as 
specified by cmd. The following cmds are available: 

IPCJSTAT Place the current value of each member of 
the data structure associated with shmid 
into the structure pointed to by buf. The 
contents of this structure are defined in 
[EINVAL] introil). {READ} 

IPCJSET Set the value of the following members of 
the data structure associated with shmid to 
the corresponding value found in the struc- 
ture pointed to by buf. 
shm_perm.uid 
shm_perm.gid 

shm_perm.mode /* only low 9 bits */ 

This cmd can only be executed by a process 
that has an effective user ID equal to either 
that of super-user or to the value of 
shmjperm.uid in the data structure associ- 
ated with shmid. 

IPCJRMID Remove the shared memory identifier 
specified by shmid from the system and des- 
troy the shared memory segment and data 
structure associated with it. This cmd can 
only be executed by a process that has an 
effective user ID equal to either that of 
super-user or to the value of shmjperm.uid 
in the data structure associated with shmid. 

SHM_LOCK Lock the shared memory segment specified 
by shmid in memory. This cmd can only be 
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executed by a process that has an effective 
usr ID equal to super-user. 

SHMJJNLOCK 

Unlock the shared memory segment 
specified by shmid. This cmd can only be 
executed by a process that has an effective 
usr ID equal to super-user. 

Shmctl will fail if one or more of the following are true: 

Shmid is not a valid shared memory identifier. 
[EINVAL] 

Cmd is not a valid command. [EINVAL] 

Cmd is equal to IPCJSTAT and {READ} operation 
permission is denied to the calling process [see 
intro (2)1 [EACCES] 

Cmd is equal to IPC_RMID or IPCJSET and the 
effective user ID of the calling process is not equal 
to that of super-user and it is not equal to the 
value of shm_perm.uid in the data structure asso- 
ciated with shmid. [EPERM] 

Cmd is equal to SHM_LOCK or SHMJJNLOCK 
and the effective user ID of the calling process is 
not equal to that of super-user. [EPERM] 

Cmd is equal to SHMJJNLOCK and the shared- 
memory segment specified by shmid is not locked 
in memory. [EINVAL] Buf points to an illegal 
address. [EFAULT] 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

shmget(2), shmop(2). 
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NAME 

shmget — get shared memory segment 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/shm.h> 

int shmget (key, size, shmflg) 

key_t key; 

int size, shmflg; 

DESCRIPTION 

Shmget returns the shared memory identifier associated with key. 

A shared memory identifier and associated data structure and 
shared memory segment of size size bytes (see introil)) are 
created for key if one of the following are true: 

Key is equal to IPC_PRIVATE. 

Key does not already have a shared memory identifier 
associated with it, and (shmflg & IPC_CREAT) is "true". 

Upon creation, the data structure associated with the new shared 
memory identifier is initialized as follows: 

Shm_perm.cuid, shmjperm.uid, shm_perm.cgid, and 
shm_perm.gid are set equal to the effective user ID and 
effective group ID, respectively, of the calling process. 

The low-order 9 bits of shmjperm.mode are set equal to 
the low-order 9 bits of shmflg. Shmsegsz is set equal to 
the value of size. 

Shmlpid, shmnattch, shmatime, and shm dtime are set 

equal to 0. 

Shm_ctime is set equal to the current time. 

Shmget will fail if one or more of the following are true: 

[EINVAL] Size is less than the system-imposed minimum or 

greater than the system-imposed maximum. 

[EACCESl A shared memory identifier exists for key but 
operation permission (see intro(2)) as specified 
by the low-order 9 bits of shmflg would not be 
granted. 
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[EINVAL] A shared memory identifier exists for key but the 

size of the segment associated with it is less than 
size and size is not equal to zero. 

[ENOENTl A shared memory identifier does not exist for key 
and (shmflg & IPC_CREAT) is "false". 

[ENOSPC] A shared memory identifier is to be created but 
the system-imposed limit on the maximum 
number of allowed shared memory identifiers sys- 
tem wide would be exceeded. 

[ENOMEMl A shared memory identifier and associated 
shared memory segment are to be created but the 
amount of available physical memory is not 
sufficient to fill the request. 

[EEXIST] A shared memory identifier exists for key but ( 

(shmflg & IPC_CREAT) and ( shmflg & 
IPC_EXCL) ) is "true". 

RETURN VALUE 

Upon successful completion, a non-negative integer, namely a 
shared memory identifier is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

intro(2), shmctl(2), shmop(2). 
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NAME 

shmop — shared memory operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/shm.h> 

char *shmat (shmid, shmaddr, shmflg) 
int shmid; 
char *shmaddr 
int shmflg; 

int shmdt (shmaddr) 
char *shmaddr 

DESCRIPTION 

Shmat attaches the shared memory segment associated with the 
shared memory identifier specified by shmid to the data segment 
of the calling process. The segment is attached at the address 
specified by one of the following criteria: 

If shmaddr is equal to zero, the segment is attached at the 
first available address as selected by the system. 

If shmaddr is not equal to zero and {shmflg & 
SHM_RND) is "true", the segment is attached at the 
address given by (shmaddr - (shmaddr modulus 
SHMLBA)). 

If shmaddr is not equal to zero and (shmflg & 
SHM RND) is "false", the segment is attached at the 
address given by shmaddr. 

The segment is attached for reading if (shmflg & SHM_RDONLY) 
is "true" {READ}, otherwise it is attached for reading and writing 
{READ/ WRITE}. 

Shmat will fail and not attach the shared memory segment if one 
or more of the following are true: 

[EINVAL] Shmid is not a valid shared memory identifier. 

[EACCESl Operation permission is denied to the calling pro- 
cess (see intro(2)). 

[ENOMEMJ The available data space is not large enough to 
accommodate the shared memory segment. 
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[EINVAL] Shmaddr is not equal to zero, and the value of 

{shmaddr - {shmaddr modulus SHMLBA)) is an 
illegal address. 

[EINVAL] Shmaddr is not equal to zero, {shmflg & 

SHM RND) is "false", and the value of shmaddr 
is an illegal address. 

[EMFILE] The number of shared memory segments 

attached to the calling process would exceed the 
system-imposed limit. 

[EINVAL] Shmdt detaches from the calling process's data 

segment the shared memory segment located at 
the address specified by shmaddr. 

[EINVAL] Shmdt will fail and not detach the shared 

memory segment if shmaddr is not the data seg- 
ment start address of a shared memory segment. 

RETURN VALUES 

Upon successful completion, the return value is as follows: 

Shmat returns the data segment start address of the 
attached shared memory segment. 

Shmdt returns a value of 0. 

Otherwise, a value of —1 is returned and errno is set to indicate 
the error. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), shmctl(2), shmget(2). 
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NAME 

signal — specify what to do upon receipt of a signal 

SYNOPSIS 

#include <signal.h> 

int (*signal (sig, func))() 
int sig; 

void (*func)(); 
DESCRIPTION 

Signal allows the calling process to choose one of three ways in 
which it is possible to handle the receipt of a specific signal. Sig 
specifies the signal and func specifies the choice. 

Sig can be assigned any one of the following except SIGKILL: 



SIGHUP 


01 


hangup 


SIGINT 


02 


interrupt 


SIGQUIT 


03* 


quit 


SIGILL 


04* 


illegal instruction (not reset when caught) 


SIGTRAP 


05* 


trace trap (not reset when caught) 


SIGIOT 


06* 


IOT instruction 


SIGEMT 


07* 


EMT instruction 


SIGFPE 


08* 


floating point exception 


SIGKILL 


09 


kill (cannot be caught or ignored) 


SIGBUS 


10* 


bus error 


SIGSEGV 


11* 


segmentation violation 


SIGSYS 


12* 


bad argument to system call 


SIGPIPE 


13 


write on a pipe with no one to read it 


SIGALRM 


14 


alarm clock 


SIGTERM 


15 


software termination signal 


SIGUSR1 


16 


user-defined signal 1 


SIGUSR2 


17 


user-defined signal 2 


SIGCLD 


18 


death of a child 






(see WARNING below) 


SIGPWR 


19 


power fail 



(see WARNING below) 



See below for the significance of the asterisk (•) in the above list. 

Func is assigned one of three values: SIG_DFL, SIGJGN, or a 
function address. The actions prescribed by these values are as 
follows: 

SIG_DFL — terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is 
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to be terminated with all of the consequences outlined 
in exit (2) . In addition a "core image" will be made in 
the current working directory of the receiving process if 
sig is one for which an asterisk appears in the above 
list and the following conditions are met: 

The effective user ID and the real user ID of 
the receiving process are equal. 

An ordinary file named core exists and is 
writable or can be created. If the file must be 
created, it will have the following properties: 

a mode of 0666 modified by the file 
creation mask (see umaskil)) 

a file owner ID that is the same as 
the effective user ID of the receiving 
process. 

a file group ID that is the same as 
the effective group ID of the receiv- 
ing process 

SIGJGN — ignore signal 

The signal sig is to be* ignored. 

Note: the signal SIGKILL cannot be ignored. 

function address — catch signal 

Upon receipt of the signal sig, the receiving process is to 
execute the signal-catching function pointed to by func. 
The signal number sig will be passed as the only argu- 
ment to the signal-catching function. Additional argu- 
ments are passed to the signal-catching function for 
hardware-generated signals. Before entering the signal- 
Catching function, the value of func for the caught signal 
will be set to SIG_DFL unless the signal is SIGILL, 
SIGTRAP, or SIGPWR. 

Upon return from the signal-catching function, the 
receiving process will resume execution at the point it was 
interrupted. 

When a signal that is to be caught occurs during a read, 
a write, an open, or an ioctl system call on a slow device 
(like a terminal; but not a file), during a pause system 
call, or during a wait system call that does not return 
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immediately due to the existence of a previously stopped 
or zombie process, the signal catching function will be 
executed and then the interrupted system call may return 
a —1 to the calling process with errno set to EINTR. 

Note: The signal SIGKILL cannot be caught. 

A call to signal cancels a pending signal sig except for a pending 
SIGKILL signal. 

Signal will fail if sig is an illegal signal number, including SIG- 
KILL. [EINVAL] 

RETURN VALUE 

Upon successful completion, signal returns the previous value of 
func for the specified signal sig. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 

SEE ALSO 

kill(2), pause(2), ptrace(2), wait(2), setjmp(3C). 
kill(l) in the UNIX Programmer's Manual— Volume 1: Com- 
mands and Utilities. 

WARNING 

Two other signals that behave differently than the signals 
described above exist in this release of the system; they are: 

SIGCLD 18 death of a child (reset when caught) 
SIGPWR 19 power fail (not reset when caught) 

There is no guarantee that, in future releases of the UNIX system, 
these signals will continue to behave as described below; they are 
included only for compatibility with other versions of the UNIX 
system. Their use in new programs is strongly discouraged. 

For these signals, func is assigned one of three values: SIGJDFL, 
SIG IGN, or a function address. The actions prescribed by these 
values of are as follows: 

SIGJDFL - ignore signal 

The signal is to be ignored. 

SIGJGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the 
calling process's child processes will not create zombie 
processes when they terminate; see exit (2) . 

function address - catch signal 

If the signal is SIGPWR, the action to be taken is the 
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same as that described above for func equal to function 
address. The same is true if the signal is SIGCLD 
except, that while the process is executing the signal- 
catching function, any received SIGCLD signals will be 
queued and the signal-catching function will be con- 
tinually reentered until the queue is empty. 

The SIGCLD affects two other system calls (wait (2), and 
exit (2)) in the following ways: 

wait If the func value of SIGCLD is set to SIGJGN and a 
wait is executed, the wait will block until all of the 
calling process's child processes terminate; it will then 
return a value of —1 with errno set to ECHILD. 

exit If in the exiting process's parent process the func value 
of SIGCLD is set to SIGJGN, the exiting process will 
not create a zombie process. 

When processing a pipeline, the shell makes the last process in 
the pipeline the parent of the proceeding processes. A process 
that may be piped into in this manner (and thus become the 
parent of other processes) should take care not to set SIGCLD to 
be caught. 
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NAME 

stat, fstat — get file status 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/stat.h> 

int stat (path, buf) 
char *path; 
struct stat *buf; 

int fstat (fildes, buf) 
int fildes; 
struct stat *buf; 

DESCRIPTION 

Path points to a path name naming a file. Read, write, or execute 
permission of the named file is not required, but all directories 
listed in the path name leading to the file must be searchable. 
Stat obtains information about the named file. 

Similarly, fstat obtains information about an open file known by 
the file descriptor fildes, obtained from a successful open, creat, 
dup,fcntl, or pipe system call. 

Buf is a pointer to a stat structure into which information is 
placed concerning the file. 

The contents of the structure pointed to by buf include the follow- 
ing members: 

ushort st mode; /* File mode; see mknod (2) */ 

ino t st ino; /* Inode number */ 

dev t st dev; /* ID of device containing */ 

/* a directory entry for this file */ 
/* ID of device */ 
/* This entry is defined only for */ 
/* character special or block special files */ 
short st nlink; / * Number of links */ 
ushort st uid; /* User ID of the file's owner */ 

ushort stjgid; /* Group ID of the file's group */ 

off t st size; /* File size in bytes */ 
time t st atime; /* Time of last access */ 
time t st mtime; / * Time of last data modification */ 
time t st ctime; / * Time of last file status change */ 

/* Times measured in seconds since */ 
/* 00:00:00 GMT, Jan. 1, 1970 */ 



dev t st rdev; 
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st_atime Time when file data was last accessed. Changed by 
the following system calls: creatil), mknod(2), 
pipe(2), utime(2), and read (2). 

st_mtime Time when data was last modified. Changed by the 
following system calls: creat(2), mknod{2), pipe {2), 
utime(2), and write (2). 

st_ctime Time when file status was last changed. Changed by 
the following system calls: chmod(2), chown(2), 
creat(2), link (2), mknod(2), pipe (2), unlink (2), 
utime(2), and write (2). 

Stat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCESl Search permission is denied for a component of 

the path prefix. 

[EFAULTl Buf or path points to an invalid address. 

Fstat will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EFAULTl Buf points to an invalid address. 

RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

chmod(2), chown(2), creat(2), link (2), mknod(2), pipe (2), 
read (2), time (2), unlink (2), utime(2), write (2). 
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NAME 

stime — set time 

SYNOPSIS 

int stime (tp) 
long *tp; 

DESCRIPTION 

Stime sets the system's idea of the time and date. Tp points to 
the value of time as measured in seconds from 00:00:00 GMT 
January 1, 1970. 

[EPERM] Stime will fail if the effective user ID of the cal- 

ling process is not super-user. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

time (2). 
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NAME 

sync — update super-block 

SYNOPSIS 

void sync ( ) 

DESCRIPTION 

Sync causes all information in memory that should be on disk to 
be written out. This includes modified super blocks, modified i- 
nodes, and delayed block I/O. 

It should be used by programs which examine a file system, for 
example fsck, df, etc. It is mandatory before a boot. 

The writing, although scheduled, is not necessarily complete upon 
return from sync. 
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NAME 

time — get time 

SYNOPSIS 

long time ((long •) 0) 

long time (tloc) 
long *tloc; 

DESCRIPTION 

Time returns the value of time in seconds since 00:00:00 GMT, 
January 1, 1970. 

If tloc (taken as an integer) is non-zero, the return value is also 
stored in the location to which tloc points. 

[EFAULT] Time will fail if tloc points to an illegal address. 

RETURN VALUE 

Upon successful completion, time returns the value of time. Oth- 
erwise, a value of —1 is returned and errno is set to indicate the 
error. 

SEE ALSO 

stime(2). 
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NAME 

times — get process and child process times 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/times.h> 

long times (buffer) 
struct tms *buffer; 

DESCRIPTION 

Times fills the structure pointed to by buffer with time-accounting 
information. The following are the contents of this structure: 

struct tms { 

timet tmsutime; 
timet tmsstime; 
timet tmscutime; 
timet tmscstime; 

}; 

This information comes from the calling process and each of its 
terminated child processes for which it has executed a wait. All 
times are in 60ths of a second on DEC processors, lOOths of a 
second on AT&T processors. 

Tms utime is the CPU time used while executing instructions in 
the user space of the calling process. 

Tms stime is the CPU time used by the system on behalf of the 
calling process. 

Tms cutime is the sum of the tmsutimes and tms cutimes of the 
child processes. 

Tms cstime is the sum of the tms _s times and tms_cstimes of the 
child processes. 

[EFAULT] Times will fail if buffer points to an illegal address. 

RETURN VALUE 

Upon successful completion, times returns the elapsed real time, in 
60ths (lOOths) of a second, since an arbitrary point in the past 
(e.g., system start-up time). This point does not change from one 
invocation of times to another. If times fails, a —1 is returned 
and errno is set to indicate the error. 

SEE ALSO 

exec(2), fork(2), time(2), wait(2). 
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NAME 

ulimit — get and set user limits 

SYNOPSIS 

long ulimit (cmd, newlimit) 
int cmd; 
long newlimit; 

DESCRIPTION 

This function provides for control over process limits. The cmd 
values available are: 

1 Get the file size limit of the process. The limit is in units of 
512-byte blocks and is inherited by child processes. Files of 
any size can be read. 

2 Set the file size limit of the process to the value of newlimit. 
Any process may decrease this limit, but only a process with 
an effective user ID of super-user may increase the limit. 
Ulimit will fail and the limit will be unchanged if a process 
with an effective user ID other than super-user attempts to 
increase its file size limit. lEPERMl 

3 Get the maximum possible break value. See brk (2) . 

RETURN VALUE 

Upon successful completion, a non-negative value is returned. 
Otherwise, a value of —1 is returned and errno is set to indicate 
the error. 

SEE ALSO 

brk (2), write (2). 
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NAME 

umask — set and get file creation mask 

SYNOPSIS 

int umask (cmask) 
int cmask; 

DESCRIPTION 

Umask sets the process's file mode creation mask to cmask and 
returns the previous value of the mask. Only the low-order 9 bits 
of cmask and the file mode creation mask are used. 

RETURN VALUE 

The previous value of the file mode creation mask is returned. 

SEE ALSO 

chmod(2), creat(2), mknod(2), open (2). 

mkdir(l), sh(l) in the UNIX Programmer's Manual— Volume 1: 
Commands and Utilities. 
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NAME 

umount — unmount a file system 

SYNOPSIS 

int umount (spec) 
char *spec; 

DESCRIPTION 

Umount requests that a previously mounted file system contained 
on the block special device identified by spec be unmounted. Spec 
is a pointer to a path name. After unmounting the file system, the 
directory upon which the file system was mounted reverts to its 
ordinary interpretation. 

Umount may be invoked only by the super-user. 

Umount will fail if one or more of the following are true: 

[EPERM] The process's effective user ID is not super-user. 

[ENXIO] Spec does not exist. 

[ENOTBLK] Spec is not a block special device. 

[EINVAL] Spec is not mounted. 

[EBUSY] A file on spec is busy. 

[EFAULTl Spec points to an illegal address. 

RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

mount (2). 



UNIX Programmer's Manual 



System Calls and Library Routines— 103 



UNAME(2) 



UNAME(2) 



NAME 

uname — get name of current UNIX system 

SYNOPSIS 

#include <sys/utsname.h> 

int uname (name) 
struct utsname *name; 

DESCRIPTION 

Uname stores information identifying the current UNIX system in 
the structure pointed to by name. 

Uname uses the structure denned in <sys/utsname.h> whose 
members are: 

char sysname[9]; 

char nodename[9l; 

char release[9]; 

char version[9]; 

char machine[9]; 

Uname returns a null-terminated character string naming the 
current UNIX system in the character array sysname. Similarly, 
nodename contains the name that the system is known by on a 
communications network. Release and version further identify the 
operating system. Machine contains a standard name that 
identifies the hardware that the UNIX system is running on. 

[EFAULTl Uname will fail if name points to an invalid address. 

RETURN VALUE 

Upon successful completion, a non-negative value is returned. 
Otherwise, —1 is returned and errno is set to indicate the error. 

SEE ALSO 

uname(l) in the UNIX Programmer's Manual — Volume 1: Com- 
mands and Utilities. 
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NAME 

unlink — remove directory entry 

SYNOPSIS 

int unlink (path) 
char *path; 

DESCRIPTION 

Unlink removes the directory entry named by the path name 
pointed to be path . 

The named file is unlinked unless one or more of the following are 
true: 

[ENOTDIRl A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of 
the path prefix. 

[EACCESl Write permission is denied on the directory con- 
taining the link to be removed. 

[EPERMl The named file is a directory and the effective 

user ID of the process is not super-user. 

[EBUSY] The entry to be unlinked is the mount point for a 

mounted file system. 



[ETXTBSY] 



[EROFS] 



The entry to be unlinked is the last link to a pure 
procedure (shared text) file that is being exe- 
cuted. 



The directory entry to be unlinked is part of a 
read-only file system. 

[EFAULTl Path points outside the process's allocated 

address space. 

When all links to a file have been removed and no process has the 
file open, the space occupied by the file is freed and the file ceases 
to exist. If one or more processes have the file open when the last 
link is removed, the removal is postponed until all references to the 
file have been closed. 
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RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

close (2), link (2), open (2). 

rm(l) in the UNIX Programmer's Manual— Volume 1: Com- 
mands and Utilities. 
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NAME 

ustat — get file system statistics 

SYNOPSIS 

#include <sys/types.h> 
#include <ustat.h> 



int ustat (dev, buf) 
int dev; 

struct ustat *buf; 
DESCRIPTION 

Ustat returns information about a mounted file system. Dev is a 
device number identifying a device containing a mounted file sys- 
tem. Buf is a pointer to a ustat structure that includes to follow- 
ing elements: 

daddr t ftfree; /* Total free blocks */ 

ino t f tinode; /* Number of free inodes */ 

char f_fname[6l; /* Filsys name */ 

char f_fpack[6l; /* Filsys pack name */ 

Ustat will fail if one or more of the following are true: 

[EINVALl Dev is not the device number of a device contain- 

ing a mounted file system. 

[EFAULT] Buf points outside the process's allocated address 

space. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of — 1 is returned and errno is set to indicate the error. 

SEE ALSO 

stat (2), fs(4). 
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NAME 

utime — set file access and modification times 

SYNOPSIS 

#include <sys/types.h> 
int utime (path, times) 
char *path; 
struct utimbuf *times; 

DESCRIPTION 

Path points to a path name naming a file. Utime sets the access 
and modification times of the named file. 

If times is NULL, the access and modification times of the file are 
set to the current time. A process must be the owner of the file or 
have write permission to use utime in this manner. 

If times is not NULL, times is interpreted as a pointer to a utim- 
buf structure and the access and modification times are set to the 
values contained in the designated structure. Only the owner of 
the file or the super-user may use utime this way. 

The times in the following structure are measured in seconds since 
00:00:00 GMT, Jan. 1, 1970. 

struct utimbuf { 

time t actime; /* access time */ 
time t modtime; /* modification time */ 

}; 

Utime will fail if one or more of the following are true: 

[ENOENT] The named file does not exist. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EACCES] Search permission is denied by a component of 

the path prefix. 

[EPERMl The effective user ID is not super-user and not 

the owner of the file and times is not NULL. 

[EACCES] The effective user ID is not super-user and not 
the owner of the file and times is NULL and 
write access is denied. 

[EROFS] The file system containing the file is mounted 

read-only. 

[EFAULT] Times is not NULL and points outside the 

process's allocated address space. 
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[EFAULT] Path points outside the process's allocated 

address space. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

stat (2). 
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NAME 

wait — wait for child process to stop or terminate 

SYNOPSIS 

int wait (statjoc) 
int *stat_loc; 

int wait ((int *)0) 

DESCRIPTION 

Wait suspends the calling process until until one of the immediate 
children terminates or until a child that is being traced stops, 
because it has hit a break point. The wait system call will return 
prematurely if a signal is received and if a child process stopped or 
terminated prior to the call on wait, return is immediate. 

If stat joc (taken as an integer) is non-zero, 16 bits of information 
called status are stored in the low order 16 bits of the location 
pointed to by statjoc. Status can be used to differentiate 
between stopped and terminated child processes and if the child 
process terminated, status identifies the cause of termination and 
passes useful information to the parent. This is accomplished in the 
following manner: 

If the child process stopped, the high order 8 bits of status 
will contain the number of the signal that caused the pro- 
cess to stop and the low order 8 bits will be set equal to 
0177. 

If the child process terminated due to an exit call, the low 
order 8 bits of status will be zero and the high order 8 bits 
will contain the low order 8 bits of the argument that the 
child process passed to exit; see exit (2). 

If the child process terminated due to a signal, the high 
order 8 bits of status will be zero and the low order 8 bits 
will contain the number of the signal that caused the ter- 
mination. In addition, if the low order seventh bit (i.e., bit 
200) is set, a "core image" will have been produced; see 
signal (2). 

If a parent process terminates without waiting for its child 
processes to terminate, the parent process ID of each child process 
is set to 1. This means the initialization process inherits the child 
processes; see intro(2). 

Wait will fail and return immediately if one or more of the follow- 
ing are true: 
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[ECHILD] 



The calling process has no existing unwaited-for 
child processes. 

Stat Joe points to an illegal address. 



[EFAULTl 



RETURN VALUE 

If wait returns due to the receipt of a signal, a value of —1 is 
returned to the calling process and errno is set to EINTR. If wait 
returns due to a stopped or terminated child process, the process 
ID of the child is returned to the calling process. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

exec (2), exit (2), fork (2), intro(2), pause (2), ptrace(2), signal (2). 

WARNING 

See WARNING in signal (2). 
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NAME 

write — write on a file 

SYNOPSIS 

int write (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup,fcntl, 
or pipe system call. 

Write attempts to write nbyte bytes from the buffer pointed to by 
buf to the file associated with the fildes. 

On devices capable of seeking, the actual writing of data proceeds 
from the position in the file indicated by the file pointer. Upon 
return from write, the file pointer is incremented by the number of 
bytes actually written. 

On devices incapable of seeking, writing always takes place start- 
ing at the current position. The value of a file pointer associated 
with such a device is undefined. 

If the 0_APPEND flag of the file status flags is set, the file pointer 
will be set to the end of the file prior to each write. 

Write will fail and the file pointer will remain unchanged if one or 
more of the following are true: 

[EBADF] Fildes is not a valid file descriptor open for writ- 

ing. 

[EPIPE and SIGPIPE signal] 

An attempt is made to write to a pipe that is not 
open for reading by any process. 

[EFBIG] An attempt was made to write a file that exceeds 

the process's file size limit or the maximum file 
size. See ulimiti.2). 

[EFAULT] Buf points outside the process's allocated address 
space. 

[EINTR] A signal was caught during the write system call. 

If a write requests that more bytes be written than there is room 
for (e.g., the ulimit (see ulimitil)) or the physical end of a 
medium), only as many bytes as there is room for will be written. 
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For example, suppose there is space for 20 bytes more in a file 
before reaching a limit. A write of 512 bytes will return 20. The 
next write of a non-zero number of bytes will give a failure return 
(except as noted below). 

If the file being written is a pipe (or FIFO) and the 0_NDELAY 
flag of the file flag word is set, then write to a full pipe (or FIFO) 
will return a count of 0. Otherwise (ONDELAY clear), writes to 
a full pipe (or FIFO) will block until space becomes available. 

RETURN VALUE 

Upon successful completion the number of bytes actually written is 
returned. Otherwise, —1 is returned and errno is set to indicate 
the error. 

SEE ALSO 

creat(2), dup(2), lseek(2), open (2), pipe (2), ulimit(2). 
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NAME 

intro — introduction to subroutines and libraries 

SYNOPSIS 

#include <stdio.h> 

#include <math.h> 

DESCRIPTION 

This section describes functions found in various libraries, other 
than those functions that directly invoke UNIX system primitives, 
which are described in Section 2 of this volume. Certain major 
collections are identified by a letter after the section number: 

(3C) These functions, together with those of Section 2 and those 
marked (3S), constitute the Standard C Library libc, which 
is automatically loaded by the C compiler, cciX). The link 
editor Id (l) searches this library under the — lc option. 
Declarations for some of these functions may be obtained 
from #include files indicated on the appropriate pages. 

(3S) These functions constitute the "standard I/O package" [see 
stdio(3S)]. These functions are in the library libc, already 
mentioned. Declarations for these functions may be 
obtained from the #include file <stdio.h>. 

(3M) These functions constitute the Math Library, libm. They 
are automatically accessed by the F77 compiler to imple- 
ment the intrinsic math functions described in section 3F. 
They are not automatically loaded by the C compiler, 
ceil); however, the link editor searches this library under 
the — lm option. Declarations for these functions may be 
obtained from the #include file <math.h>. Several gen- 
erally useful mathematical constants are also defined there 
[see math (5)]. 

(3X) Various specialized libraries. The files in which these 
libraries are found are given on the appropriate pages. 

(3F) These functions constitute the F77 intrinsic functions 
library, HbF77, which includes the standard FORTRAN 
intrinsic functions as a subset. These functions are 
automatically available to the FORTRAN programmer and 
require no special invocation of the compiler. 

DEFINITIONS 

A character is any bit pattern able to fit into a byte on the 
machine. The null character is a character with value 0, 
represented in the C language as '\0'. A character array is a 
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sequence of characters. A null -terminated character array is a 
sequence of characters, the last of which is the null character. A 
string is a designation for a null -terminated character array. The 
null string is a character array containing only the null character. 
A NULL pointer is the value that is obtained by casting 0 into a 
pointer. The C language guarantees that this value will not match 
that of any legitimate pointer, so many functions that return 
pointers return it to indicate an error. NULL is defined as 0 in 
<stdio.h>; the user can include an appropriate definition if not 
using <stdio.h>. 

Many groups of FORTRAN intrinsic functions have generic func- 
tion names that do not require explicit or implicit type declaration. 
The type of the function will be determined by the type of its 
argument (s). For example, the generic function max will return 
an integer value if given integer arguments (maxO), a real value if 
given real arguments (amaxl), or a double-precision value if given 
double-precision arguments (dmaxl). 

FILES 

/lib/libc.a 

/lib/libm.a 

/usr/lib/libF77.a 

SEE ALSO 

intro(2), stdio(3S), math (5). 

ar(l), cc(l), f77(l), ld(l), lint(l), nm(l) in the UNIX 
Programmer's Manual —Volume 1: Commands and Utilities. 

DIAGNOSTICS 

Functions in the C and Math Libraries (3C and 3M) may return 
the conventional values 0 or ±HUGE (the largest-magnitude 
single-precision floating-point numbers; HUGE is defined in the 
<math.h> header file) when the function is undefined for the 
given arguments or when the value is not representable. In these 
cases, the external variable errno [see introil)] is set to the value 
EDOM or ERANGE. As many of the FORTRAN intrinsic func- 
tions use the routines found in the Math Library, the same conven- 
tions apply. 

WARNING 

Many of the functions in the libraries call and/or refer to other 
functions and external variables described in this section and in 
section 2 {System Calls) . If a program inadvertantly defines a 
function or external variable with the same name, the presumed 
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library version of the function or external variable may not be 
loaded. The lint (I) program checker reports name conflicts of this 
kind as "multiple declarations" of the names in question. 
Definitions for sections 2, 3C, and 3S are checked automatically. 
Other definitions can be included by using the —1 option (for exam- 
ple, — lm includes definitions for the Math Library, section 3M). 
Use of lint is highly recommended. 
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NAME 

a641, 164a — convert between long integer and base-64 ASCII 
string 

SYNOPSIS 

long a641 (s) 
char *s; 

char *164a (1) 
long 1; 

DESCRIPTION 

These functions are used to maintain numbers stored in base-64 
ASCII characters. This is a notation by which long integers can be 
represented by up to six characters; each character represents a 
"digit" in a radix-64 notation. 

The characters used to represent "digits" are . for 0, / for 1, 0 
through 9 for 2—11, A through Z for 12—37, and a through z for 
38-63. 

A641 takes a pointer to a null-terminated base-64 representation 
and returns a corresponding long value. If the string pointed to by 
s contains more than six characters, a64l will use the first six. 

L64a takes a long argument and returns a pointer to the 
corresponding base-64 representation. If the argument is 0, 164 a 
returns a pointer to a null string. 

BUGS 

The value returned by 164a is a pointer into a static buffer, the 
contents of which are overwritten by each call. 
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NAME 

abort — generate an IOT fault 

SYNOPSIS 

int abort ( ) 

DESCRIPTION 

Abort first closes all open files if possible, then causes an IOT sig- 
nal to be sent to the process. This usually results in termination 
with a core dump. 

It is possible for abort to return control if SIGIOT is caught or 
ignored, in which case the value returned is that of the kill (2) sys- 
tem call. 

SEE ALSO 

exit (2), kill (2), signal (2). 

sdb(l) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 

DIAGNOSTICS 

If SIGIOT is neither caught nor ignored, and the current directory 
is writable, a core dump is produced and the message "abort — 
core dumped" is written by the shell. 
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NAME 

abs — return integer absolute value 

SYNOPSIS 

int abs (i) 
int i; 

DESCRIPTION 

Abs returns the absolute value of its integer operand. 

BUGS 

In two's-complement representation, the absolute value of the 
negative integer with largest magnitude is undefined. Some imple- 
mentations trap this error, but others simply ignore it. 

SEE ALSO 

floor(3M). 
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NAME 

bsearch — binary search a sorted table 

SYNOPSIS 

#include <search.h> 

char *bsearch ((char •) key, (char *) base, nel, sizeof (*key), 
compar) 
unsigned nel; 
int (*compar)( ); 

DESCRIPTION 

Bsearch is a binary search routine generalized from Knuth (6.2.1) 
Algorithm B. It returns a pointer into a table indicating where a 
datum may be found. The table must be previously sorted in 
increasing order according to a provided comparison function. Key 
points to a datum instance to be sought in the table. Base points 
to the element at the base of the table. Nel is the number of ele- 
ments in the table. Compar is the name of the comparison func- 
tion, which is called with two arguments that point to the elements 
being compared. The function must return an integer less than, 
equal to, or greater than zero as accordinly the first argument is to 
be considered less than, equal to, or greater than the second. 

EXAMPLE 

The example below searches a table containing pointers to nodes 
consisting of a string and its length. The table is ordered alpha- 
betically on the string in the node pointed to by each entry. 

This code fragment reads in strings and either finds the 
corresponding node and prints out the string and its length, or 
prints an error message. 

#include <stdio.h> 
#include < search. h> 

#define TABSIZE 1000 

struct node { /♦ stored in the table */ 

char *string; 
int length; 

}; 

struct node table[TABSIZEl; /* table to be searched */ 
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struct node *node_ptr, node; 

int node_compare( ); /* compare 2 nodes */ 

char str_space[20]; /* space to read string into */ 



node.string = strspace; 

while (scanf("%s", node.string) != EOF) { 

nodejjtr = (struct node *)bsearch((char *)(&node), 
(char *) table, TABSIZE, 
sizeof (struct node), nodecompare) ; 
if (node_ptr !- NULL) { 

(void)printfC'string = %20s, length - %d\n", 

node jptr— > string, node_ptr— > length) ; 

} else { 

(void)printf("not found: %s\n", node.string); 

} 

} 

} 

/* 

This routine compares two nodes based on an 
alphabetical ordering of the string field. 

♦/ 

int 

node_compare(nodel, node2) 
struct node *nodel, *node2; 
{ 

return strcmp (node 1— > string, node2—> string); 

} 

NOTES 

The pointers to the key and the element at the base of the table 
should be of type pointer-to-element, and cast to type pointer-to- 
character. 

The comparison function need not compare every byte, so arbitrary 
data may be contained in the elements in addition to the values 
being compared. 

Although declared as type pointer-to-character, the value returned 
should be cast into type pointer-to-element. 
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SEE ALSO 

hsearch(3C), lsearch(3C), qsort(3C), tsearch(3C). 
DIAGNOSTICS 

A NULL pointer is returned if the key cannot be found in the 
table. 
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NAME 

clock — report CPU time used 

SYNOPSIS 

long clock ( ) 

DESCRIPTION 

Clock returns the amount of CPU time (in microseconds) used 
since the first call to clock. The time reported is the sum of the 
user and system times of the calling process and its terminated 
child processes for which it has executed wait (2) or system (3S) . 

The resolution of the clock is 10 milliseconds on AT&T 3B com- 
puter processors, 16.667 milliseconds on Digital Equipment Cor- 
poration processors. 

SEE ALSO 

times (2), wait (2), system (3S). 

BUGS 

The value returned by clock is defined in microseconds for compa- 
tibility with systems that have CPU clocks with much higher reso- 
lution. Because of this, the value returned will wrap around after 
accumulating only 2147 seconds of CPU time (about 36 minutes). 
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NAME 

toupper, tolower, toupper, tolower, toascii — translate characters 

SYNOPSIS 

#include <ctype.h> 

int toupper (c) 
int c; 

int tolower (c) 
int c; 

int toupper (c) 
int c; 

int _tolower (c) 
int c; 

int toascii (c) 
int c; 

DESCRIPTION 

Toupper and tolower have as domain the range of getcOS): the 
integers from —1 through 255. If the argument of toupper 
represents a lower-case letter, the result is the corresponding 
upper-case letter. If the argument of tolower represents an 
upper-case letter, the result is the corresponding lower-case letter. 
All other arguments in the domain are returned unchanged. 

The macros toupper and Jolower, are macros that accomplish 
the same thing as toupper and tolower but have restricted 
domains and are faster, toupper requires a lower-case letter as 
its argument; its result is the corresponding upper-case letter. The 
macro tolower requires an upper-case letter as its argument; its 
result is the corresponding lower-case letter. Arguments outside 
the domain cause undefined results. 

Toascii yields its argument with all bits turned off that are not 
part of a standard ASCII character; it is intended for compatibility 
with other systems. 

SEE ALSO 

ctypeOC), getc(3S). 
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NAME 

crypt, setkey, encrypt — generate DES encryption 

SYNOPSIS 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, edflag) 
char *block; 
int edflag; 

DESCRIPTION 

Crypt is the password encryption function. It is based on the NBS 
Data Encryption Standard (DES), with variations intended (among 
other things) to frustrate use of hardware implementations of the 
DES for key search. 

Key is a user's typed password. Salt is a two-character string 
chosen from the set [a-zA-ZO-9./]; this string is used to perturb 
the DES algorithm in one of 4096 different ways, after which the 
password is used as the key to encrypt repeatedly a constant string. 
The returned value points to the encrypted password. The first 
two characters are the salt itself. 

The setkey and encrypt entries provide (rather primitive) access to 
the actual DES algorithm. The argument of setkey is a character 
array of length 64 containing only the characters with numerical 
value 0 and 1. If this string is divided into groups of 8, the low- 
order bit in each group is ignored; this gives a 56-bit key which is 
set into the machine. This is the key that will be used with the 
above mentioned algorithm to encrypt or decrypt the string block 
with the function encrypt. 

The argument to the encrypt entry is a character array of length 
64 containing only the characters with numerical value 0 and 1. 
The argument array is modified in place to a similar array 
representing the bits of the argument after having been subjected 
to the DES algorithm using the key set by setkey. If edflag is 
zero, the argument is encrypted; if non-zero, it is decrypted. 
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SEE ALSO 

getpass (3C) , passwd (4) . 

login (1), passwd(l) in the UNIX Programmer's Manual— 
Volume 1: Commands and Utilities. 

BUGS 

The return value points to static data that are overwritten by each 
call. 
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NAME 

ctime, localtime, gmtime, asctime, tzset — convert date and time to 
string 

SYNOPSIS 

#include <time.h> 

char *ctime (clock) 
long *clock; 

struct tm Hocaltime (clock) 
long *clock; 

struct tm *gmtime (clock) 
long *clock; 

char *asctime (tm) 
struct tm *tm; 

extern long timezone; 

extern int daylight; 

extern char *tzname[2l; 

void tzset ( ) 

DESCRIPTION 

Ctime converts a long integer, pointed to by clock, representing 
the time in seconds since 00:00:00 GMT, January 1, 1970, and 
returns a pointer to a 26-character string in the following form. 
All the fields have constant width. 

Sun Sep 16 01:03:52 1973\n\0 

Localtime and gmtime return pointers to "tm" structures, 
described below. Localtime corrects for the time zone and possible 
Daylight Savings Time; gmtime converts directly to Greenwich 
Mean Time (GMT), which is the time the UNIX system uses. 

Asctime converts a "tm" structure to a 26-character string, as 
shown in the above example, and returns a pointer to the string. 

Declarations of all the functions and externals, and the "tm" struc- 
ture, are in the <time.h> header file. The structure declaration 

is: 

struct tm { 

int tm sec; 
int tm min; 
int tm hour; 



/* seconds (0 - 59) */ 
/♦ minutes (0 - 59) */ 
/* hours (0 - 23) */ 
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int tm mday; 
int tm mon; 
int tm_year; 
int tm wday; 
int tm_yday; 
int tmisdst; 



/* day of month (1 - 31) */ 
/* month of year (0 - 11) */ 
/* year - 1900 */ 



/* day of week (Sunday = 0) */ 
/* day of year (0 - 365) */ 



}; 



Tm isdst is non-zero if Daylight Savings Time is in effect. 

The external long variable timezone contains the difference, in 
seconds, between GMT and local standard time (in EST, timezone 
is 5*60*60); the external variable daylight is non-zero if and only 
if the standard U.S.A. Daylight Savings Time conversion should be 
applied. The program knows about the peculiarities of this conver- 
sion in 1974 and 1975; if necessary, a table for these years can be 
extended. 

If an environment variable named TZ is present, asctime uses the 
contents of the variable to override the default time zone. The 
value of TZ must be a three-letter time zone name, followed by a 
number representing the difference between local time and 
Greenwich Mean Time in hours, followed by an optional three- 
letter name for a daylight time zone. For example, the setting for 
New Jersey would be EST5EDT. The effects of setting TZ are thus 
to change the values of the external variables timezone and day- 
light', in addition, the time zone names contained in the external 
variable 

char *tzname[2l - { "EST", "EDT" }; 

are set from the environment variable TZ. The function tzset sets 
these external variables from TZ; tzset is called by asctime and 
may also be called explicitly by the user. 

Note that in most installations, TZ is set by default when the user 
logs on, to a value in the local /etc/profile file (see profile (A)). 



The return values point to static data whose content is overwritten 
by each call. 



SEE ALSO 



time(2), getenv(3C), profile(4), environ(5). 



BUGS 
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NAME 

isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, 
isprint, isgraph, iscntrl, isascii — classify characters 

SYNOPSIS 

#include <ctype.h> 

int isalpha (c) 
int c; 

DESCRIPTION 

These macros classify character-coded integer values by table 
lookup. Each is a predicate returning nonzero for true, zero for 
false. Isascii is denned on all integer values; the rest are denned 
only where isascii is true and on the single non-ASCII value EOF 
(-1 - see stdioOS)). 



isalpha c is a letter. 

isupper c is an upper-case letter. 

islower c is a lower-case letter. 

isdigit c is a digit [0-9]. 

isxdigit c is a hexadecimal digit [0-9], [A-F] or [a-f]. 

isalnum c is an alphanumeric (letter or digit). 

isspace c is a space, tab, carriage return, new-line, verti- 

cal tab, or form-feed. 

ispunct c is a punctuation character (neither control nor 

alphanumeric). 

isprint c is a printing character, code 040 (space) 

through 0176 (tilde). 

isgraph c is a printing character, like isprint except false 

for space. 

iscntrl c is a delete character (0177) or an ordinary con- 

trol character (less than 040) . 

isascii c is an ASCII character, code less than 0200. 
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DIAGNOSTICS 

If the argument to any of these macros is not in the domain of the 
function, the result is undefined. 

SEE ALSO 

stdio(3S), ascii(5). 
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NAME 

dial — establish an out-going terminal line connection 

SYNOPSIS 

#include <dial.h> 

int dial (call) 
CALL call; 

void undial (fd) 
int fd; 

DESCRIPTION 

Dial returns a file-descriptor for a terminal line open for 
read/write. The argument to dial is a CALL structure (defined in 
the <dial.h> header file). 

When finished with the terminal line, the calling program must 
invoke undial to release the semaphore that has been set during 
the allocation of the terminal device. 

The definition of CALL in the <dial.h> header file is: 



typedef struct { 






struct termio *attr; 


/* pointer to termio attribute struct */ 


int 


baud; 


/* transmission data rate */ 


int 


speed; 


/* 212A modem: low=300, high=1200 */ 


char 


*line; 


/» device name for out-going line */ 


char 


*telno; 


/* pointer to tel-no digits string */ 


int 


modem; 


/* specify modem control for direct lines */ 


char 


*device; 


/♦Will hald the name of the device used 






to make a connection */ 


int 


devlen; 


/* The length of the device used 






to make connection */ 



} CALL; 



The CALL element speed is intended only for use with an outgoing 
dialed call, in which case its value should be either 300 or 1200 to 
identify the 1 1 3 A modem, or the high- or low-speed setting on the 
212A modem. Note that the 113A modem or the low-speed setting 
of the 212A modem will transmit at any rate between 0 and 300 
bits per second. However, the high-speed setting of the 212A 
modem transmits and receivers at 1200 bits per secound only. The 
CALL element baud is for the desired transmission baud rate. For 
example, one might set baud to 110 and speed to 300 (or 1200). 
However, if speed set to 1200 baud must be set to high (1200). 
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If the desired terminal line is a direct line, a string pointer to its 
device-name should be placed in the line element in the CALL 
structure. Legal values for such terminal device names are kept in 
the L-devices file. In this case, the value of the baud element 
need not be specified as it will be determined from the L-devices 
file. 

The telno element is for a pointer to a character string represent- 
ing the telephone number to be dialed. Such numbers may consist 
only of symbols described on the act/ (7). The termination symbol 
will be supplied by the dial function, and should not be included in 
the telno string passed to dial in the CALL structure. 

The CALL element modem is used to specify modem control for 
direct lines. This element should be non-zero if modem control is 
required. The CALL element attr is a pointer to a termio struc- 
ture, as defined in the termio.h header file. A NULL value for this 
pointer element may be passed to the dial function, but if such a 
structure is included, the elements specified in it will be set for the 
outgoing terminal line before the connection is established. This is 
often important for certain attributes such as parity and baud-rate. 

The CALL element device is used to hold the device name (cul..) 
that establishes the connection. 

The CALL element devjen is the length of the device name that is 
copied into the array device. 

FILES 

/usr/lib/uucp/L-devices 

/usr/ spool/uucp/LCK. . tty -device 

SEE ALSO 

uucp(lC) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
alarm (2), read (2), write (2). 

acu(7), termio (7) in the UNIX System Administrator Reference 
Manual. 

DIAGNOSTICS 

On failure, a negative value indicating the reason for the failure 
will be returned. Mnemonics for these negative indices as listed 
here are defined in the <dial.h> header file. 

INTRPT -1 /* interrupt occurred */ 

D HUNG —2 /* dialer hung (no return from write) */ 

NO ANS —3 /* no answer within 10 seconds */ 
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ILLBD 


-4 


/* illegal baud-rate */ 


A_PROB 


-5 


/* acu problem (openO failure) */ 


L PROB 


-6 


/* line problem (openO failure) */ 


NO_Ldv 


-7 


/* can't open LDEVS file */ 


DVNTA 


-8 


/* requested device not available */ 


DVNTK 


-9 


/* requested device not known */ 


NOBDA 


-10 


/* none available at requested baud */ 


NOBDK 


-11 


/* no device known at requested baud */ 



WARNINGS 

Including the <dial.h> header file automatically includes the 
<termio.h> header file. 

The above routine uses <stdio.h>, which causes it to increase the 
size of programs, not otherwise using standard I/O, more than 
might be expected. 

BUGS 

An alarm (2) system call for 3600 seconds is made (and caught) 
within the dial module for the purpose of "touching" the LCK.. file 
and constitutes the device allocation semaphore for the terminal 
device. Otherwise, uucpilO may simply delete the LCK.. entry 
on its 90-minute clean-up rounds. The alarm may go off while the 
user program is in a read (2) or write (2) system call, causing an 
apparent error return. If the user program expects to be around 
for an hour or more, error returns from reads should be checked 
for (en-no** =EINTR), and the read possibly reissued. 
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NAME 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, 
seed48, lcong48 — generate uniformly distributed pseudo-random 
numbers 

SYNOPSIS 

double drand48 ( ) 

double erand48 (xsubi) 
unsigned short xsubi[3l; 

long Irand48 ( ) 

long nrand48 (xsubi) 
unsigned short xsubi[3l; 

long mrand48 ( ) 

long jrand48 (xsubi) 
unsigned short xsubi[3l; 

void srand48 (seedval) 
long seedval; 

unsigned short *seed48 (seedl6v) 
unsigned short seedl6v[3l; 

void lcong48 (param) 
unsigned short paraml7l; 

DESCRIPTION 

This family of functions generates pseudo-random numbers using 
the well-known linear congruential algorithm and 48 -bit integer 
arithmetic. 

Functions drand48 and erand48 return non-negative double- 
precision floating-point values uniformly distributed over the inter- 
val [0.0, 1.0). 

Functions lrand48 and nrand48 return non-negative long integers 
uniformly distributed over the interval [0, 2 31 ). 

Functions mrand48 and jrand48 return signed long integers uni- 
formly distributed over the interval [-2 31 , 2 31 ). 

Functions srand48, seed48 and lcong48 are initialization entry 
points, one of which should be invoked before either drand48, 
lrand48 or mrand48 is called. (Although it is not recommended 
practice, constant default initializer values will be supplied 
automatically if drand48, lrand48 or mrand48 is called without a 
prior call to an initialization entry point.) Functions erand48, 
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nrand48 and jrand48 do not require an initialization entry point to 
be called first. 

All the routines work by generating a sequence of 48-bit integer 
values, X h according to the linear congruential formula 

X n+l - (aX n + c) mod m n>0. 

The parameter w=2 48 ; hence 48 -bit integer arithmetic is per- 
formed. Unless lcong48 has been invoked, the multiplier value a 
and the addend value c are given by 

a = 5DEECE66D 16 = 273673163155 8 
c = B 16 - 13 8 . 

The value returned by any of the functions drand48, erand48, 
lrand48, nrand48, mrand48 or jrand48 is computed by first gen- 
erating the next 48-bit X { in the sequence. Then the appropriate 
number of bits, according to the type of data item to be returned, 
are copied from the high-order (leftmost) bits of X t and 
transformed into the returned value. 

The functions drand48, lrand48 and mrand48 store the last 48-bit 
Xj generated in an internal buffer; that is why they must be initial- 
ized prior to being invoked. The functions erand48, nrand48 and 
jrand48 require the calling program to provide storage for the suc- 
cessive X t values in the array specified as an argument when the 
functions are invoked. That is why these routines do not have to 
be initialized; the calling program merely has to place the desired 
initial value of X t into the array and pass it as an argument. By 
using different arguments, functions erand48, nrand48 and 
jrand48 allow separate modules of a large program to generate 
several independent streams of pseudo-random numbers, i.e., the 
sequence of numbers in each stream will not depend upon how 
many times the routines have been called to generate numbers for 
the other streams. 

The initializer function srand48 sets the high-order 32 bits of X t to 
the 32 bits contained in its argument. The low-order 16 bits of X t 
are set to the arbitrary value 330E 16 . 

The initializer function seed48 sets the value of X t to the 48-bit 
value specified in the argument array. In addition, the previous 
value of Xi is copied into a 48 -bit internal buffer, used only by 
seed48, and a pointer to this buffer is the value returned by 
seed48. This returned pointer, which can just be ignored if not 
needed, is useful if a program is to be restarted from a given point 
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at some future time — use the pointer to get at and store the last 
X t value, and then use this value to reinitialize via seed48 when 
the program is restarted. 

The initialization function lcong48 allows the user to specify the 
initial X h the multiplier value a, and the addend value c. Argu- 
ment array elements param[0-2] specify X h param[3-5] specify 
the multiplier a, and paramfo] specifies the 16-bit addend c. 
After lcong48 has been called, a subsequent call to either srand48 
or seed48 will restore the "standard" multiplier and addend 
values, a and c, specified on the previous page. 

NOTES 

On most computers, the routines are coded in portable C. The 
source code for the portable version can even be used on computers 
which do not have floating-point arithmetic. In such a situation, 
functions drand48 and erand48 do not exist; instead, they are 
replaced by the two new functions below. 

long irand48 (m) 
unsigned short m; 

long krand48 (xsubi, m) 
unsigned short xsubi[3], m; 

Functions irand48 and krand48 return non-negative long integers 
uniformly distributed over the interval [0, m— 1]. 

SEE ALSO 

rand(3C). 
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NAME 

ecvt, fcvt, gcvt — convert floating-point number to string 

SYNOPSIS 

char *ecvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *fcvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *gcvt (value, ndigit, buf) 
double value; 
int ndigit; 
char *buf; 

DESCRIPTION 

Ecvt converts value to a null-terminated string of ndigit digits and 
returns a pointer thereto. The high-order digit is non-zero, unless 
the value is zero. The low-order digit is rounded. The position of 
the decimal point relative to the beginning of the string is stored 
indirectly through decpt (negative means to the left of the 
returned digits). The decimal point is not included in the returned 
string. If the sign of the result is negative, the word pointed to by 
sign is non-zero, otherwise it is zero. 

Fcvt is identical to ecvt, except that the correct digit has been 
rounded for printf "%f" (FORTRAN F-format) output of the 
number of digits specified by ndigit. 

Gcvt converts the value to a null-terminated string in the array 
pointed to by buf and returns buf. It attempts to produce ndigit 
significant digits in FORTRAN F-format if possible, otherwise E- 
format, ready for printing. A minus sign, if there is one, or a 
decimal point will be included as part of the returned string. 
Trailing zeros are suppressed. 

SEE ALSO 

printf (3S). 

BUGS 

The values returned by ecvt and fcvt point to a single static data 
array whose content is overwritten by each call. 
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NAME 

end, etext, edata — last locations in program 

SYNOPSIS 

extern end; 
extern etext; 
extern edata; 

DESCRIPTION 

These names refer neither to routines nor to locations with 
interesting contents. The address of etext is the first address 
above the program text, edata above the initialized data region, 
and end above the uninitialized data region. 

When execution begins, the program break (the first location 
beyond the data) coincides with en d, but the program break may 
be reset by the routines of brk(2), malloc(3C), standard 
input/output (stdio (3S)), the profile (— p) option of cc(X), and so 
on. Thus, the current value of the program break should be deter- 
mined by sbrk(O) (see brk(2)). 

SEE ALSO 

brk(2), malloc(3C), stdio (3S). 

cc(l) in the UNIX Programmer's Manual —Volume 1: Commands 
and Utilities. 
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NAME 

frexp, ldexp, modf — manipulate parts of floating-point numbers 

SYNOPSIS 

double frexp (value, eptr) 
double value; 
int *eptr; 

double ldexp (value, exp) 
double value; 
int exp; 

double modf (value, iptr) 
double value, *iptr; 

DESCRIPTION 

Every non-zero number can be written uniquely as x * 2 n , where 
the "mantissa" (fraction) x is in the range 0.5 < < 1.0, and 
the "exponent" n is an integer. Frexp returns the mantissa of a 
double value, and stores the exponent indirectly in the location 
pointed to by eptr. If value is zero, both results returned by frexp 
are zero. 

Ldexp returns the quantity value * 2 exp . 

Modf returns the signed fractional part of value and stores the 
integral part indirectly in the location pointed to by iptr. 

DIAGNOSTICS 

If ldexp would cause overflow, ±HUGE is returned (according to 
the sign of value), and errno is set to ERANGE. 
If ldexp would cause underflow, zero is returned and errno is set 
to ERANGE. 
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NAME 

ftw — walk a file tree 

SYNOPSIS 

#include <ftw.h> 

int ftw (path, fn, depth) 
char *path; 
int (*fn) ( ); 
int depth; 

DESCRIPTION 

Ftw recursively descends the directory hierarchy rooted in path. 
For each object in the hierarchy, ftw calls /«, passing it a pointer 
to a null-terminated character string containing the name of the 
object, a pointer to a stat structure (see stat (2)) containing infor- 
mation about the object, and an integer. Possible values of the 
integer, defined in the <ftw.h> header file, are FTW F for a file, 
FTW D for a directory, FTWDNR for a directory that cannot be 
read, and FTW NS for an object for which stat could not success- 
fully be executed. If the integer is FTW DNR, descendants of that 
directory will not be processed. If the integer is FTW_NS, the stat 
structure will contain garbage. An example of an object that 
would cause FTW_NS to be passed to fn would be a file in a direc- 
tory with read but without execute (search) permission. 

Ftw visits a directory before visiting any of its descendants. 

The tree traversal continues until the tree is exhausted, an invoca- 
tion of fn returns a nonzero value, or some error is detected within 
ftw (such as an I/O error). If the tree is exhausted, ftw returns 
zero. If fn returns a nonzero value, ftw stops its tree traversal and 
returns whatever value was returned by fn. If ftw detects an 
error, it returns —1, and sets the error type in errno. 

Ftw uses one file descriptor for each level in the tree. The depth 
argument limits the number of file descriptors so used. If depth is 
zero or negative, the effect is the same as if it were 1. Depth must 
not be greater than the number of file descriptors currently avail- 
able for use. Ftw will run more quickly if depth is at least as 
large as the number of levels in the tree. 

SEE ALSO 

stat (2), mallocOC). 
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BUGS 

Because ftw is recursive, it is possible for it to terminate with a 
memory fault when applied to very deep file structures. 
It could be made to run faster and use less storage on deep struc- 
tures at the cost of considerable complexity. 

Ftw uses mallocOO to allocate dynamic storage during its opera- 
tion. If ftw is forcibly terminated, such as by longjmp being exe- 
cuted by fn or an interrupt routine, ftw will not have a chance to 
free that storage, so it will remain permanently allocated. A safe 
way to handle interrupts is to store the fact that an interrupt has 
occurred, and arrange to have fn return a nonzero value at its next 
invocation. 
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NAME 

getcwd — get path-name of current working directory 

SYNOPSIS 

char *getcwd (buf, size) 
char *buf; 
int size; 

DESCRIPTION 

Getcwd returns a pointer to the current directory path-name. The 
value of size must be at least two greater than the length of the 
path-name to be returned. 

If buf is a NULL pointer, getcwd will obtain size bytes of space 
using malloc (3C). In this case, the pointer returned by getcwd 
may be used as the argument in a subsequent call to free. 

The function is implemented by using popen(3S) to pipe the out- 
put of the pwd(l) command into the specified string space. 

EXAMPLE 

char *cwd, *getcwd(); 



if ((cwd = getcwd((char *)NULL, 64)) — NULL) { 
perror("pwd"); 
exit(l); 

} 

printf("%s\n", cwd); 

SEE ALSO 

malloc (3C), popen(3S). 

pwd(l) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 

DIAGNOSTICS 

Returns NULL with errno set if size is not large enough, or if an 
error ocurrs in a lower-level function. 
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NAME 

getenv — return value for environment name 

SYNOPSIS 

char »getenv (name) 
char *name; 

DESCRIPTION 

Getenv searches the environment list (see environ (5)) for a string 
of the form name = value, and returns a pointer to the value in the 
current environment if such a string is present, otherwise a NULL 
pointer. 

SEE ALSO 

exec (2), putenv(3C), environ (5). 
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NAME 

getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent — get 
group file entry 

SYNOPSIS 

#include <grp.h> 

struct group *getgrent ( ) 

struct group *getgrgid (gid) 
int gid; 

struct group *getgrnam (name) 
char *name; 

void setgrent ( ) 

void endgrent ( ) 

struct group *fgetgrent (f) 
FILE *f; 

DESCRIPTION 

Getgrent, getgrgid and getgrnam each return pointers to an object 
with the following structure containing the broken-out fields of a 
line in the /etc/group file. Each line contains a "group" structure, 
defined in the <grp.h> header file. 

struct group { 

char *gr_name; /* the name of the group */ 

char *gr_passwd; /* the encrypted group password */ 

int grjgid; /* the numerical group ID */ 

char **gr_mem; /* vector of pointers to member names */ 

}; 

Getgrent when first called returns a pointer to the first group 
structure in the file; thereafter, it returns a pointer to the next 
group structure in the file; so, successive calls may be used to 
search the entire file. Getgrgid searches from the beginning of the 
file until a numerical group id matching gid is found and returns a 
pointer to the particular structure in which it was found. Get- 
grnam searches from the beginning of the file until a group name 
matching name is found and returns a pointer to the particular 
structure in which it was found. If an end-of-file or an error is 
encountered on reading, these functions return a NULL pointer. 

A call to setgrent has the effect of rewinding the group file to 
allow repeated searches. Endgrent may be called to close the 
group file when processing is complete. 
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Fgetgrent returns a pointer to the next group structure in the 
stream /, which matches the format of /etc/group. 

FILES 

/etc/group 

SEE ALSO 

getlogin(3C), getpwent(3C), group(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to increase 
the size of programs, not otherwise using standard I/O, more than 
might be expected. 

BUGS 

All information is contained in a static area, so it must be copied if 
it is to be saved. 
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NAME 

getlogin — get login name 

SYNOPSIS 

char * getlogin ( ); 

DESCRIPTION 

Getlogin returns a pointer to the login name as found in 
/etc/utmp. It may be used in conjunction with getpwnam to 
locate the correct password file entry when the same user ID is 
shared by several login names. 

If getlogin is called within a process that is not attached to a ter- 
minal, it returns a NULL pointer. The correct procedure for deter- 
mining the login name is to call cuserid, or to call getlogin and if 
it fails to call getpwuid. 

FILES 

/etc/utmp 
SEE ALSO 

cuserid(3S), getgrent(3C), getpwent(3C), utmp(4). 

DIAGNOSTICS 

Returns the NULL pointer if name is not found. 

BUGS 

The return values point to static data whose content is overwritten 
by each call. 
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NAME 

getopt — get option letter from argument vector 

SYNOPSIS 

int getopt (argc, argv, optstring) 
int argc; 
char **argv; 
char '"optstring; 

extern char *optarg; 
extern int optind; 

DESCRIPTION 

Getopt retunrs the next option letter in argv that matches a letter 
in optstring. Optstring is a string of recognized option letters; if a 
letter is followed by a colon, the option is expected to have an 
argument that may or may not be separated from it by white 
space. Optarg is set to point to the start of the option argument. 

Getopt places in optind the argv index of the next argument to be 
processed. Because optind is external, it is normally initialized to 
zero automatically before the first call to getopt. 

When all options have been processed, getopt returns EOF. The 
special option — may be used to delimit the end of the options; 
EOF will be returned, and — will be skipped. 

DIAGNOSTICS 

Getopt prints an error message on stderr and returns a question 
mark (?) when it encounters an option letter not included in opt- 
string. 

WARNING 

The above routine uses <stdio.h> which causes it to increase the 
size of programs, not otherwise using standard I/O, more than 
might be expected. 

SEE ALSO 

getopt (1). 
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NAME 

getpass — read a password 

SYNOPSIS 

char *getpass (prompt) 
char *prompt; 

DESCRIPTION 

Getpass reads up to a newline or EOF from the file /dev/tty, after 
prompting on the standard error output with the null-terminated 
string prompt and disabling echoing. A pointer is returned to a 
null-terminated string of at most 8 characters. If /dev/tty cannot 
be opened, a NULL pointer is returned. An interrupt will ter- 
minate input and send an interrupt signal to the calling program 
before returning. 

FILES 

/dev/tty 

SEE ALSO 

crypt (3C). 

WARNING 

The above routine uses <stdio.h>, which causes it to increase the 
size of programs not otherwise using standard I/O, more than 
might be expected. 

BUGS 

The return value points to static data whose content is overwritten 
by each call. 
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NAME 

getpw — get name from UID 

SYNOPSIS 

int getpw (uid, buf) 
int uid; 
char *buf; 

DESCRIPTION 

Getpw searches the password file for a user id number that equals 
uid, copies the line of the password file in which uid was found 
into the array pointed to by buf, and returns 0. Getpw returns 
non-zero if uid cannot be found. 

This routine is included only for compatibility with prior systems 
and should not be used; see getpwent (3C) for routines to use 
instead. 

FILES 

/etc/passwd 

SEE ALSO 

getpwent (3 C) , pass wd (4) . 

DIAGNOSTICS 

Getpw returns non-zero on error. 

WARNING 

The above routine uses <stdio.h>, which causes it to increase, 
more than might be expected, the size of programs not otherwise 
using standard I/O. 
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NAME 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent — 
get password file entry 

SYNOPSIS 

#include <pwd.h> 

struct passwd *getpwent ( ) 

struct passwd *getpwuid (uid) 
int uid; 

struct passwd *getpwnam (name) 
char *name; 

void setpwent ( ) 

void endpwent ( ) 

struct passwd *fgetpwent (f) 
FILE *f; 

DESCRIPTION 

Getpwent, getpwuid and getpwnam each returns a pointer to an 
object with the following structure containing the broken-out fields 
of a line in the /etc/passwd file. Each line in the file contains a 
"passwd" structure, declared in the <pwd.h> header file: 

struct passwd { 



char 


♦pwname; 


char 


*pw_passwd; 


int 


pwuid; 


int 


pw jgid; 


char 


*pw_age; 


char 


♦pwcomment; 


char 


*pw_gecos; 


char 


♦pwdir; 


char 


♦pwshell; 



}; 

This structure is declared in <pwd.h> so it is not necessary to 
redeclare it. 

The pw comment field is unused; the others have meanings 
described in passwd (4) . 

Getpwent when first called returns a pointer to the first passwd 
structure in the file; thereafter, it returns a pointer to the next 
passwd structure in the file; so successive calls can be used to 
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search the entire file. Getpwuid searches from the beginning of 
the file until a numerical user id matching uid is found and 
returns a pointer to the particular structure in which it was found. 
Getpwnam searches from the beginning of the file until a login 
name matching name is found, and returns a pointer to the partic- 
ular structure in which it was found. If an end-of-file or an error 
is encountered on reading, these functions return a NULL pointer. 

A call to setpwent has the effect of rewinding the password file to 
allow repeated searches. Endpwent may be called to close the 
password file when processing is complete. 

Fgetpwent returns a pointer to the next passwd structure in the 
stream /, which matches the format of /etc/passwd. 

FILES 

/etc/passwd 

SEE ALSO 

getlogin(3C), getgrent(3C), passwd (4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to increase 
the size of programs, not otherwise using standard I/O, more than 
might be expected. 

BUGS 

All information is contained in a static area, so it must be copied if 
it is to be saved. 
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NAME 



getutent, getutid, getutline, pututline, setutent, endutent, utmp- 
name — access utmp file entry 



SYNOPSIS 

#include <utmp.h> 

struct utmp *getutent ( ) 

struct utmp *getutid (id) 
struct utmp *id; 

struct utmp *getutline (line) 
struct utmp *line; 

void pututline (utmp) 
struct utmp *utmp; 

void setutent ( ) 

void endutent ( ) 

void utmpname (file) 
char *file; 

DESCRIPTION 

Getutent, getutid and getutline each return a pointer to a struc- 
ture of the following type: 



struct utmp { 

char 

char 

char 

short 

short 

struct 
short 
short 

} utexit; 



ut_user[8l; 

ut_id[4l; 

ut_line[12]; 

ut_pid; 

uttype; 

exitstatus { 

etermination; 

e exit; 



timet uttime; 



/* User login name */ 

/* /etc/inittab id (usually line #) */ 

/* device name (console, lnxx) */ 

/* process id */ 

/* type of entry */ 

/* Process termination status */ 
/♦ Process exit status */ 
/* The exit status of a process 
* marked as DEAD_PROCESS. */ 
/* time entry was made */ 



}; 

Getutent reads in the next entry from a utmp-Mke, file. If the file 
is not already open, it opens it. If it reaches the end of the file, it 
fails. 

Getutid searches forward from the current point in the utmp file 
until it finds an entry with a ut type matching id — >ut_type if 
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the type specified is RUNLVL, BOOT TIME, OLD TIME or 
NEWTIME. If the type specified in id is INIT_PROCESS, 
LOGIN_PROCESS, USER_PROCESS or DEAD_PROCESS, then 
getutid will return a pointer to the first entry whose type is one of 
these four and whose utjd field matches id — >utjd. If the end 
of file is reached without a match, it fails. 

Getutline searches forward from the current point in the utmp file 
until it finds an entry of the type LOGIN_PROCESS or 
USER PROCESS which also has a utjine string matching the 
line — >ut line string. If the end of file is reached without a 
match, it fails. 

Pututline writes out the supplied utmp structure into the utmp 
file. It uses getutid to search forward for the proper place if it 
finds that it is not already at the proper place. It is expected that 
normally the user of pututline will have searched for the proper 
entry using one of the getut routines. If so, pututline will not 
search. If pututline does not find a matching slot for the new 
entry, it will add a new entry to the end of the file. 

Setutent resets the input stream to the beginning of the file. This 
should be done before each search for a new entry if it is desired 
that the entire file be examined. 

Endutent closes the currently open file. 

Utmpname allows the user to change the name of the file exam- 
ined, from /etc/utmp to any other file. It is most often expected 
that this other file will be /etc/wtmp. If the file does not exist, this 
will not be apparent until the first attempt to reference the file is 
made. Utmpname does not open the file. It just closes the old file 
if it is currently open and saves the new file name. 

FILES 

/etc/utmp 
/etc/wtmp 

SEE ALSO 

ttyslotOO, utmp (4). 

DIAGNOSTICS 

A NULL pointer is returned upon failure to read, whether for per- 
missions or having reached the end of file, or upon failure to write. 
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NAME 

hsearch, hcreate, hdestroy — manage hash search tables 

SYNOPSIS 

#include <search.h> 

ENTRY *hsearch (item, action) 
ENTRY item; 
ACTION action; 

int hcreate (nel) 
unsigned nel; 

void hdestroy ( ) 

DESCRIPTION 

Hsearch is a hash-table search routine generalized from Knuth 
(6.4) Algorithm D. It returns a pointer into a hash table indicat- 
ing the location at which an entry can be found. Item is a struc- 
ture of type ENTRY (denned in the <search.fi > header file) con- 
taining two pointers: item.key points to the comparison key, and 
item.data points to any other data to be associated with that key. 
(Pointers to types other than character should be cast to pointer- 
to-character.) Action is a member of an enumeration type 
ACTION indicating the disposition of the entry if it cannot be 
found in the table. ENTER indicates that the item should be 
inserted in the table at an appropriate point. FIND indicates that 
no entry should be made. Unsuccessful resolution is indicated by 
the return of a NULL pointer. 

Hcreate allocates sufficient space for the table, and must be called 
before hsearch is used. Nel is an estimate of the maximum 
number of entries that the table will contain. This number may be 
adjusted upward by the algorithm in order to obtain certain 
mathematically favorable circumstances. 

Hdestroy destroys the search table, and may be followed by 
another call to hcreate. 

NOTES 

Hsearch uses open addressing with a multiplicative hash function. 
However, its source code has many other options available which 
the user may select by compiling the hsearch source with the fol- 
lowing symbols defined to the preprocessor: 

DIV Use the remainder modulo table size as the 

hash function instead of the multiplicative 
algorithm. 
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Use a User Supplied Comparison Routine for 
ascertaining table membership. The routine 
should be named hcompar and should behave 
in a mannner similar to strcmp (see 
stringOO). 

Use a linked list to resolve collisions. If this 
option is selected, the following other options 
become available. 

START Place new entries at the begin- 

ning of the linked list (default 
is at the end) . 

SORTUP Keep the linked list sorted by 
key in ascending order. 

SORTDOWN Keep the linked list sorted by 
key in descending order. 

Additionally, there are preprocessor flags for obtaining debugging 
printout (-DDEBUG) and for including a test driver in the calling 
routine (— DDRIVER). The source code should be consulted for 
further details. 

EXAMPLE 

The following example will read in strings followed by two 
numbers and store them in a hash table, discarding duplicates. It 
will then read in strings and find the matching entry in the hash 
table and print it out. 

#include <stdio.h> 
#include < search. h> 

struct info { /* this is the info stored in the table */ 

int age, room; /* other than the key. */ 

}; 

#define NUM_EMPL 5000 /* # elements in search table */ 

main( ) 
{ 

/* space to store strings */ 
char string_space[NUM_EMPL*20l; 
/* space to store employee info */ 
struct info info spacelNUM EMPL]; 
/* next avail space in string space */ 
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char *str_ptr = stringspace; 

/* next avail space in infospace */ 

struct info *info_ptr — info_space; 

ENTRY item, *found_item, *hsearch( ); 

/* name to look for in table •/ 

char name to _find[30l; 

int i = 0; 

/* create table */ 

(void) hcreate(NUM_EMPL); 

while (scanf("%s%d%d", str_ptr, &info_ptr->age, 

&info_ptr->room) !- EOF && i++ < NUM_EMPL) { 

/* put info in structure, and structure in item */ 

item.key — strjptr; 

item.data = (char *)info_ptr; 

str_ptr += strlen(str_ptr) + 1; 

infojptr++; 

/* put item into table */ 
(void) hsearchOtem, ENTER); 

} 

/* access table */ 

item.key — name_to_find; 

while (scanf("%s", item.key) != EOF) { 

if ((foundjtem - hsearchOtem, FIND)) != NULL) { 
/* if item is in the table */ 
(void) printf ("found %s, age = %d, room = %d\n", 
foundjtem— > key, 

((struct info *) foundjtem— > data)— > age, 
((struct info *) foundjtem— > data)— > room); 

} else { 

(void) printf ("no such employee %s\n", 
name to find) 

} 

} 

} 

SEE ALSO 

bsearch(3C), lsearch(3C), malloc(3C), malloc(3X), string(3C), 
tsearchOC). 
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DIAGNOSTICS 

Hsearch returns a NULL pointer if either the action is FIND and 
the item could not be found or the action is ENTER and the table 
is full. 

Hcreate returns zero if it cannot allocate sufficient space for the 
table. 

WARNING 

Hsearch and hcreate use malloc (3C) to allocate space. 

BUGS 

Only one hash search table may be active at any given time. 



UNIX Programmer's Manual 



System Calls and Library Routines— 159 



L3TOLOC) 



L3TOLC3C) 



NAME 

13tol, ltol3 — convert between 3-byte integers and long integers 

SYNOPSIS 

void 13tol (lp, cp, n) 
long *lp; 
char *cp; 
int n; 

void ltoI3 (cp, lp, n) 
char *cp; 
long *lp; 
int n; 

DESCRIPTION 

L3tol converts a list of n three-byte integers packed into a charac- 
ter string pointed to by cp into a list of long integers pointed to by 
lp. 

Ltol3 performs the reverse conversion from long integers Up) to 
three-byte integers (cp). 

These functions are useful for file-system maintenance where the 
block numbers are three bytes long. 

SEE ALSO 

fs(4). 

BUGS 

Because of possible differences in byte ordering, the numerical 
values of the long integers are machine-dependent. 
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NAME 

lockf — record locking on files 

SYNOPSIS 

# include <unistd.h> 



lockf (fildes, function, size) long size; int Aides, function; 
DESCRIPTION 

The lockf call will allow sections of a file to be locked (advisory 
write locks). (Mandatory or enforcement mode record locks are 
not currently available.) Locking calls from other processes which 
attempt to lock the locked file section will either return an error 
value or be put to sleep until the resource becomes unlocked. All 
the locks for a process are removed when the process terminates. 
[See fcntlil) for more information about record locking.] 

Fildes is an open file descriptor. The file descriptor must have 
OWRONLY or O RDWR permission in order to establish a lock 
with this function call. 

Function is a control value which specifies the action to be taken. 
The permissible values for function are defined in <unistd.h> as 
follows: 



#define FJJLOCK 0 /* 

#define F_LOCK 1 /* 

#define FTLOCK 2 /♦ 

#define FTEST 3 /* 



Unlock previously locked section */ 
Lock section for exclusive use */ 
Test/lock section for exclusive use */ 
Test for other processes locks */ 



All other values of function are reserved for future extensions and 
will result in an error return if not implemented. 

F TEST is used to detect if a lock by another process is present on 
the specified section. F LOCK and F TLOCK both lock a section of 
a file if the section is available. F UNLOCK removes locks from a 
section of the file. 

Size is the number of contiguous bytes to be locked or unlocked. 
The resource to be locked starts at the current offset in the file and 
extends forward for positive size and backward for negative size. 
If size is zero, the section from current offset through the largest 
file offset is locked (i.e., from current offset through the present or 
any future end-of-file). An area need not be allocated to a file in 
order to be locked, as such locks may exist past end-of-file. 

UNIX Programmer's Manual System Calls and Library Routines— 161 



LOCKFOC) 



LOCKFOC) 



The sections locked with F LOCK or FTLOCK may, in whole or in 
part, contain or be contained by a previously locked section for the 
same process. When this occurs, or if adjacent sections occur, the 
sections are combined into a single section. If the request requires 
that a new element be added to the table of active locks and this 
table is already full, an error is returned, and the new section is 
not locked. 

F_LOCK and F TLOCK requests differ only by the action taken if 
the resource is not available. F LOCK will cause the calling pro- 
cess to sleep until the resource is available. F TLOCK will cause 
the function to return a —1 and set errno to [EACCESSl error if 
the section is already locked by another process. 

F ULOCK requests may, in whole or in part, release one or more 
locked sections controlled by the process. When sections are not 
fully released, the remaining sections are still locked by the pro- 
cess. Releasing the center section of a locked section requires an 
additional element in the table of active locks. If this table is full, 
an [EDEADLKl error is returned and the requested section is not 
released. 

A potential for deadlock occurs if a process controlling a locked 
resource is put to sleep by accessing another process's locked 
resource. Thus calls to lock or fcntl scan for a deadlock prior to 
sleeping on a locked resource. An error return is made if sleeping 
on the locked resource would cause a deadlock. 

Sleeping on a resource is interrupted with any signal. The 
alarm(2) command may be used to provide a timeout facility in 
applications which require this facility. 

ERRORS 

The lockf utility will fail if one or more of the following are true: 
[EBADFl 

Fildes is not a valid open descriptor. 
[EACCESS] 

Cmd is F TLOCK or F TEST and the section is already 
locked by another process. 
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[EDEADLK] 

Cmd is F LOCK or F TLOCK and a deadlock would occur. 
Also the cmd is either of the above or F ULOCK and the 
number of entries in the lock table would exceed the 
number allocated on the system. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 

CAVEATS 

Unexpected results may occur in processes that do buffering in the 
user address space. The process may later read/write data which 
is/was locked. The standard I/O package is the most common 
source of unexpected buffering. 

SEE ALSO 

close (2), creat(2), fcntl(2), intro(2), open (2), read (2), write (2). 
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NAME 

lsearch, lfind — linear search and update 

SYNOPSIS 

#include <stdio.h> 
#include <search.h> 

char *lsearch ((char *)key, (char *)base, nelp, sizeof(*key), 
compar) 
unsigned *nelp; 
int (*compar)( ); 

char *lfind ((char *)key, (char *)base, nelp, sizeof(*key), corn- 
par) 

unsigned *nelp; 
int (*compar)( ); 

DESCRIPTION 

Lsearch is a linear search routine generalized from Knuth (6.1) 
Algorithm S. It returns a pointer into a table indicating where a 
datum may be found. If the datum does not occur, it is added at 
the end of the table. Key points to the datum to be sought in the 
table. Base points to the first element in the table. Nelp points to 
an integer containing the current number of elements in the table. 
The integer is incremented if the datum is added to the table. 
Compar is the name of the comparison function which the user 
must supply (strcmp, for example). It is called with two argu- 
ments that point to the elements being compared. The function 
must return zero if the elements are equal and non-zero otherwise. 

Lfind is the same as lsearch except that if the datum is not found, 
it is not added to the table. Instead, a NULL pointer is returned. 

NOTES 

The pointers to the key and the element at the base of the table 
should be of type pointer-to-element, and cast to type pointer-to- 
character. 

The comparison function need not compare every byte, so arbitrary 
data may be contained in the elements in addition to the values 
being compared. 

Although declared as type pointer-to-character, the value returned 
should be cast into type pointer-to-element. 
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EXAMPLE 

This fragment will read in < TABSIZE strings of length < 
ELSIZE and store them in a table, eliminating duplicates. 

#include <stdio.h> 
#include <search.h> 

#define TABSIZE 50 
#define ELSIZE 120 

char linelELSIZE], tab[TABSIZE][ELSIZE], *lsearch( ); 
unsigned nel = 0; 
int strcmp( ); 

while (fgetsOine, ELSIZE, stdin) !- NULL && 
nel < TABSIZE) 

(void) lsearchOine, (char *)tab, &nel, 
ELSIZE, strcmp); 

SEE ALSO 

bsearch(3C), hsearch(3C), tsearch(3C). 

DIAGNOSTICS 

If the searched for datum is found, both Isearch and Ifind return a 
pointer to it. Otherwise, Ifind returns NULL and Isearch returns 
a pointer to the newly added element. 

BUGS 

Undefined results can occur if there is not enough room in the 
table to add a new item. 
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NAME 

malloc, free, realloc, calloc — main memory allocator 

SYNOPSIS 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *real!oc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 

DESCRIPTION 

Malloc and free provide a simple general-purpose memory alloca- 
tion package. Malloc returns a pointer to a block of at least size 
bytes suitably aligned for any use. 

The argument to free is a pointer to a block previously allocated 
by malloc; after free is performed this space is made available for 
further allocation, but its contents are left undisturbed. 

Undefined results will occur if the space assigned by malloc is 
overrun or if some random number is handed to free. 

Malloc allocates the first big enough contiguous reach of free 
space found in a circular search from the last block allocated or 
freed, coalescing adjacent free blocks as it searches. It calls sbrk 
(see brk(2)) to get more memory from the system when there is 
no suitable space already free. 

Realloc changes the size of the block pointed to by ptr to size 
bytes and returns a pointer to the (possibly moved) block. The 
contents will be unchanged up to the lesser of the new and old 
sizes. If no free block of size bytes is available in the storage 
arena, then realloc will ask malloc to enlarge the arena by size 
bytes and will then move the data to the new space. 

Realloc also works if ptr points to a block freed since the last call 
of malloc, realloc, or calloc; thus sequences of free, malloc and 
realloc can exploit the search strategy of malloc to do storage 
compaction. 

Calloc allocates space for an array of nelem elements of size 
elsize. The space is initialized to zeros. 
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Each of the allocation routines returns a pointer to space suitably 
aligned (after possible pointer coercion) for storage of any type of 
object. 

SEE ALSO 

brk(2), malloc(3X). 

DIAGNOSTICS 

M alloc, realloc and calloc return a NULL pointer if there is no 
available memory or if the arena has been detectably corrupted by 
storing outside the bounds of a block. When this happens the 
block pointed to by ptr may be destroyed. 

NOTE 

Search time increases when many objects have been allocated; that 
is, if a program allocates but never frees, then each successive allo- 
cation takes longer. For an alternate, more flexible implementa- 
tion, see mallocOX). 
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NAME 

memccpy, memchr, memcmp, memcpy, memset — memory opera- 
tions 

SYNOPSIS 

#include < memory .h> 

char *memccpy (si, s2, c, n) 
char *sl, *s2; 
int c, n; 

char *memchr (s, c, n) 
char »s; 
int c, n; 

int memcmp (si, s2, n) 
char *sl, *s2; 
int n; 

char *memcpy (si, s2, n) 
char *sl, *s2; 
int n; 

char *memset (s, c, n) 
char *s; 
int c, n; 

DESCRIPTION 

These functions operate as efficiently as possible on memory areas 
(arrays of characters bounded by a count, not terminated by a null 
character). They do not check for the overflow of any receiving 
memory area. 

Memccpy copies characters from memory area s2 into si, stopping 
after the first occurrence of character c has been copied, or after n 
characters have been copied, whichever comes first. It returns a 
pointer to the character after the copy of c in si, or a NULL 
pointer if c was not found in the first n characters of s2. 

Memchr returns a pointer to the first occurrence of character c in 
the first n characters of memory area s, or a NULL pointer if c 
does not occur. 

Memcmp compares its arguments, looking at the first n characters 
only, and returns an integer less than, equal to, or greater than 0, 
according as si is lexicographically less than, equal to, or greater 
than s2. 
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Memcpy copies n characters from memory area s2 to si. It 
returns si. 

Memset sets the first n characters in memory area s to the value 
of character c. It returns s. 

NOTE 

For user convenience, all these functions are declared in the 
optional < memory. h> header file. 

BUGS 

Memcmp uses native character comparison, which is unsigned on 
on some machines. Thus the sign of the value returned when one 
of the characters has its high-order bit set is implementation- 
dependent. 

Character movement is performed differently in different imple- 
mentations. Thus overlapping moves may yield surprises. 
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NAME 

mktemp — make a unique file name 

SYNOPSIS 

char * mktemp (template) 
char *template; 

DESCRIPTION 

Mktemp replaces the contents of the string pointed to by template 
by a unique file name, and returns the address of template. The 
string in template should look like a file name with six trailing Xs; 
mktemp will replace the Xs with a letter and the current process 
ID. The letter will be chosen so that the resulting name does not 
duplicate an existing file. 

SEE ALSO 

getpid(2), tmpfile(3S), tmpnam(3S). 

BUGS 

It is possible to run out of letters. 
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NAME 

monitor — prepare execution profile 

SYNOPSIS 

#include <mon.h> 

void monitor (lowpc, highpc, buffer, bufsize, nfunc) 
int (•lowpcM ), (*highpc)( ); 
WORD *buffer; 
int bufsize, nfunc; 

DESCRIPTION 

An executable program created by cc — p automatically includes 
calls for monitor with default parameters; monitor needn't be 
called explicitly except to gain fine control over profiling. 

Monitor is an interface to profilil). Lowpc and highpc are the 
addresses of two functions; buffer is the address of a (user sup- 
plied) array of bufsize WORDs (defined in the <mon.h> header 
file). Monitor arranges to record a histogram of periodically sam- 
pled values of the program counter, and of counts of calls of cer- 
tain functions, in the buffer. The lowest address sampled is that of 
lowpc and the highest is just below highpc. Lowpc may not equal 
0 for this use of monitor. At most nfunc call counts can be kept; 
only calls of functions compiled with the profiling option — p of 
ceil) are recorded. (Except on the PDP-11, the C Library and 
Math Library supplied when cc — p is used also have call counts 
recorded.) 

For the results to be significant, especially where there are small, 
heavily used routines, it is suggested that the buffer be no more 
than a few times smaller than the range of locations sampled. 

To profile the entire program, it is sufficient to use 

extern etext; 

monitor ((int (*)())2, etext, buf, bufsize, nfunc); 

Etext lies just above all the program text; see end (3C) . 

To stop execution monitoring and write the results on the file 
mon.out, use 

monitor ((int (*)())0, 0, 0, 0, 0); 

Prof (l) can then be used to examine the results. 
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FILES 

mon.out 

/lib/libp/libca 

/lib/libp/libm.a 

SEE ALSO 

profil(2), end(3C). 

cc(l), prof(l) in the UNIX Programmer's Manual— Volume I: 
Commands and Utilities. 
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NAME 

nlist — get entries from name list 

SYNOPSIS 

#include <nlist.h> 

int nlist (file-name, nl) 
char *file-name; 
struct nlist *nl; 

DESCRIPTION 

Nlist examines the name list in the executable file whose name is 
pointed to by file -name, and selectively extracts a list of values 
and puts them in the array of nlist structures pointed to by nl. 
The name list nl consists of an array of structures containing 
names of variables, types and values. The list is terminated with a 
null name; that is, a null string is in the name position of the 
structure. Each variable name is looked up in the name list of the 
file. If the name is found, the type and value of the name are 
inserted in the next two fields. The type field will be set to 0 
unless the file was compiled with the — g option. If the name is not 
found, both entries are set to 0. See a.outiA) for a discussion of 
the symbol table structure. 

This function is useful for examining the system name list kept in 
the file /unix. In this way programs can obtain system addresses 
that are up to date. 

NOTES 

The < nlist. h> header file is automatically included by 
<a.out.h> for compatability. However, if the only information 
needed from <a.out.h> is for use of nlist, then including 
<a.out.h> is discouraged. If <a.out.h> is included, the line 
"#undef n name" may need to follow it. 

SEE ALSO 

a. out (4). 

DIAGNOSTICS 

All value entries are set to 0 if the file cannot be read or if it does 
not contain a valid name list. 

Nlist returns —1 upon error; otherwise it returns 0. 
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NAME 

perror, errno, syserrlist, sysnerr — system error messages 

SYNOPSIS 

void perror (s) 
char *s; 

extern int errno; 
extern char *sys_errlist[ J; 
extern int sysjierr; 
DESCRIPTION 

Perror produces a message on the standard error output, describ- 
ing the last error encountered during a call to a system or library 
function. The argument string s is printed first, then a colon and 
a blank, then the message and a new-line. To be of most use, the 
argument string should include the name of the program that 
incurred the error. The error number is taken from the external 
variable errno, which is set when errors occur but not cleared 
when non-erroneous calls are made. 

To simplify variant formatting of messages, the array of message 
strings sys errlist is provided; errno can be used as an index in 
this table to get the message string without the new-line. Sys nerr 
is the largest message number provided for in the table; it should 
be checked because new error codes may be added to the system 
before they are added to the table. 

SEE ALSO 

intro(2). 
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NAME 

putenv — change or add value to environment 

SYNOPSIS 

int putenv (string) 
char *string; 

DESCRIPTION 

String points to a string of the form "name —value." Putenv 
makes the value of the environment variable name equal to value 
by altering an existing variable or creating a new one. In either 
case, the string pointed to by string becomes part of the environ- 
ment, so altering the string will change the environment. The 
space used by string is no longer used once a new string-defining 
name is passed to putenv. 

DIAGNOSTICS 

Putenv returns non-zero if it was unable to obtain enough space 
via malloc for an expanded environment, otherwise zero. 

SEE ALSO 

exec (2), getenv(3C), malloc (3C), environ (5). 

WARNINGS 

Putenv manipulates the environment pointed to by environ, and 
can be used in conjunction with getenv. However, envp (the third 
argument to main) is not changed. 
This routine uses malloc (3C) to enlarge the environment. 
After putenv is called, environmental variables are not in alphabet- 
ical order. 

A potential error is to call putenv with an automatic variable as 
the argument, then exit the calling function while string is still 
part of the environment. 
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NAME 

putpwent — write password file entry 

SYNOPSIS 

#include <pwd.h> 

int putpwent (p, f) 
struct passwd *p; 
FILE *f; 

DESCRIPTION 

Putpwent is the inverse of getpwent (30. Given a pointer to a 
passwd structure created by getpwent (or getpwuid or getpwnam), 
putpwent writes a line on the stream /, which matches the format 
of /etc/passwd. 

DIAGNOSTICS 

Putpwent returns non-zero if an error was detected during its 
operation, otherwise zero. 

SEE ALSO 

getpwent (3 C). 

WARNING 

The above routine uses <stdio.h>, which causes it to increase the 
size of programs, not otherwise using standard I/O, more than 
might be expected. 
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NAME 

qsort — quicker sort 
SYNOPSIS 

void qsort ((char *) base, nel, sizeof (*base), compar) 

unsigned nel; 

int (*compar)( ); 

DESCRIPTION 

Qsort is an implementation of the quicker-sort algorithm. It sorts 
a table of data in place. 

Base points to the element at the base of the table. Nel is the 
number of elements in the table. Compar is the name of the com- 
parison function, which is called with two arguments that point to 
the elements being compared. As the function must return an 
integer less than, equal to, or greater than zero, so must the first 
argument to be considered be less than, equal to, or greater than 
the second. 

NOTES 

The pointer to the base of the table should be of type pointer-to- 
element, and cast to type pointer-to-character. 
The comparison function need not compare every byte, so arbitrary 
data may be contained in the elements in addition to the values 
being compared. 

The order in the output of two items which compare as equal is 
unpredictable. 

SEE ALSO 

bsearch(3C), lsearch(3C), stringOC). 

sort(l) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
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NAME 

rand, srand — simple random-number generator 

SYNOPSIS 

int rand ( ) 

void srand (seed) 
unsigned seed; 

DESCRIPTION 

Rand uses a multiplicative congruential random-number generator 
with period 2 32 that returns successive pseudo-random numbers in 
the range from 0 to 2 15 — 1. 

Srand can be called at any time to reset the random-number gen- 
erator to a random starting point. The generator is initially seeded 
with a value of 1 . 

NOTE 

The spectral properties of rand leave a great deal to be desired. 
Drand48 (3C) provides a much better, though more elaborate, 
random-number generator. 

SEE ALSO 

drand48(3C). 



178— System Calls and Library Routines 



UNIX Programmer's Manual 



SETJMPOC) 



SETJMPOC) 



NAME 

setjmp, longjmp — non-local goto 

SYNOPSIS 

#include <setjmp.h> 

int setjmp (env) 
jmpbuf env; 

void longjmp (env, val) 
jmp buf env; 
int val; 

DESCRIPTION 

These functions are useful for dealing with errors and interrupts 
encountered in a low-level subroutine of a program. 

Setjmp saves its stack environment in env (whose type, jmp buf, 
is denned in the <setjmp.h> header file) for later use by 
longjmp . It returns the value 0. 

Longjmp restores the environment saved by the last call of setjmp 
with the corresponding env argument. After longjmp is com- 
pleted, program execution continues as if the corresponding call of 
setjmp (which must not itself have returned in the interim) had 
just returned the value val. Longjmp cannot cause setjmp to 
return the value 0. If longjmp is invoked with a second argument 
of 0, setjmp will return 1. All accessible data had values as of the 
time longjmp was called. 

SEE ALSO 

signal (2). 

WARNING 

If longjmp is called even though env was never primed by a call to 
setjmp, or when the last such call was in a function which has 
since returned, absolute chaos is guaranteed. 
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NAME 

sleep — suspend execution for interval 

SYNOPSIS 

unsigned sleep (seconds) 
unsigned seconds; 

DESCRIPTION 

The current process is suspended from execution for the number of 
seconds specified by the argument. The actual suspension time 
may be less than that requested for two reasons: (l) Because 
scheduled wakeups occur at fixed 1 -second intervals, (on the 
second, according to an internal clock) and (2) because any caught 
signal will terminate the sleep following execution of that signal's 
catching routine. Also, the suspension time may be longer than 
requested by an arbitrary amount due to the scheduling of other 
activity in the system. The value returned by sleep will be the 
"unslept" amount (the requested time minus the time actually 
slept) in case the caller had an alarm set to go off earlier than the 
end of the requested sleep time, or premature arousal due to 
another caught signal. 

The routine is implemented by setting an alarm signal and pausing 
until it (or some other signal) occurs. The previous state of the 
alarm signal is saved and restored. The calling program may have 
set up an alarm signal before calling sleep. If the sleep time 
exceeds the time till such alarm signal, the process sleeps only 
until the alarm signal would have occurred. The caller's alarm 
catch routine is executed just before the sleep routine returns. But 
if the sleep time is less than the time till such alarm, the prior 
alarm time is reset to go off at the same time it would have 
without the intervening sleep. 

SEE ALSO 

alarm (2), pause (2), signal (2). 
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NAME 

ssignal, gsignal — software signals 

SYNOPSIS 

#include <signal.h> 

int (*ssignal (sig, action) )( ) 
int sig, (*action)( ); 

int gsignal (sig) 
int sig; 

DESCRIPTION 

Ssignal and gsignal implement a software facility similar to sig- 
nal (2). This facility is used by the Standard C Library to enable 
users to indicate the disposition of error conditions, and is also 
made available to users for their own purposes. 

Software signals made available to users are associated with 
integers in the inclusive range 1 through 15. A call to ssignal asso- 
ciates a procedure, action, with the software signal sig; the 
software signal, sig, is raised by a call to gsignal. Raising a 
software signal causes the action established for that signal to be 
taken. 

The first argument to ssignal is a number identifying the type of 
signal for which an action is to be established. The second argu- 
ment defines the action; it is either the name of a (user-defined) 
action function or one of the manifest constants SIGJDFL (default) 
or SIGJGN (ignore). Ssignal returns the action previously esta- 
blished for that signal type; if no action has been established or the 
signal number is illegal, ssignal returns SIG_DFL. 

Gsignal raises the signal identified by its argument, sig: 

If an action function has been established for sig, then that 
action is reset to SIGJDFL and the action function is entered 
with argument sig. Gsignal returns the value returned to it 
by the action function. 

If the action for sig is SIG_IGN, gsignal returns the value 1 
and takes no other action. 

If the action for sig is SIGJDFL, gsignal returns the value 0 
and takes no other action. 

If sig has an illegal value or no action was ever specified for 
sig, gsignal returns the value 0 and takes no other action. 
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SEE ALSO 

signal (2). 

NOTES 

There are some additional signals with numbers outside the range 
1 through 15 which are used by the Standard C Library to indi- 
cate error conditions. Thus, some signal numbers outside the 
range 1 through 15 are legal, although their use may interfere 
with the operation of the Standard C Library. 
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NAME 

ftok — standard interprocess communication package 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 

keyt ftok (path, id) 
char *path; 
char id; 

DESCRIPTION 

All interprocess communication facilities require the user to supply 
a key to be used by the msgget (2), semget(2), and shmget (2) sys- 
tem calls to obtain interprocess communication identifiers. One 
suggested method for forming a key is to use the ftok subroutine 
described below. Another way to compose keys is to include the 
project ID in the most significant byte and to use the remaining 
portion as a sequence number. There are many other ways to 
form keys, but it is necessary for each system to define standards 
for forming them. If some standard is not adhered to, it will be 
possible for unrelated processes to unintentionally interfere with 
each other's operation. Therefore, it is strongly suggested that the 
most significant byte of a key in some sense refer to a project so 
that keys do not conflict across a given system. 

Ftok returns a key based on path and id that is usable in subse- 
quent msgget, semget, and shmget system calls. Path must be the 
path name of an existing file that is accessible to the process. Id is 
a character which uniquely identifies a project. Note that ftok will 
return the same key for linked files when called with the same id 
and that it will return different keys when called with the same file 
name but different ids. 

SEE ALSO 

intro(2), msgget (2), semget (2), shmget (2). 

DIAGNOSTICS 

Ftok returns (keyjt) —1 if path does not exist or if it is not acces- 
sible to the process. 

WARNING 

If the file whose path is passed to ftok is removed when keys still 
refer to the file, future calls to ftok with the same path and id will 
return an error. If the same file is recreated, then ftok is likely to 
return a different key than it did the original time it was called. 
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NAME 

strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr, 
strrchr, strpbrk, strspn, strcspn, strtok — string operations 

SYNOPSIS 

#include <string.h> 

char *strcat (si, s2) 
char *sl, *s2; 

char *strncat (si, s2, n) 
char *sl, *s2; 
int n; 

int strcmp (si, s2) 
char *sl, *s2; 

int strncmp (si, s2, n) 
char *sl, *s2; 
int n; 

char *strcpy (si, s2) 
char *sl, *s2; 

char *strncpy (si, s2, n) 
char *sl, *s2; 
int n; 

int strlen (s) 
char *s; 

char *strchr (s, c) 
char *s; 
int c; 

char *strrchr (s, c) 
char *s; 
int c; 

char *strpbrk (si, s2) 
char *sl, *s2; 

int strspn (si, s2) 
char *sl, *s2; 

int strcspn (si, s2) 
char *sl, *s2; 

char *strtok (si, s2) 
char *sl, *s2; 
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DESCRIPTION 

The arguments si, s2 and s point to strings (arrays of characters 
terminated by a null character). The functions s treat, strncat, 
strcpy, and strncpy all alter si. These functions do not check for 
overflow of the array pointed to by si. 

Strcat appends a copy of string s2 to the end of string si. Strncat 
appends at most n characters. Each returns a pointer to the null- 
terminated result. 

Strcmp compares its arguments and returns an integer less than, 
equal to, or greater than 0, according as si is lexicographically less 
than, equal to, or greater than s2. Strncmp makes the same com- 
parison but looks at at most n characters. 

Strcpy copies string s2 to si, stopping after the null character has 
been copied. Strncpy copies exactly n characters, truncating s2 or 
adding null characters to si if necessary. The result will not be 
null-terminated if the length of s2 is n or more. Each function 
returns si. 

Strlen returns the number of characters in s, not including the ter- 
minating null character. 

Strchr (strrchr) returns a pointer to the first (last) occurrence of 
character c in string s, or a NULL pointer if c does not occur in 
the string. The null character terminating a string is considered to 
be part of the string. 

Strpbrk returns a pointer to the first occurrence in string si of any 
character from string s2, or a NULL pointer if no character from 
s2 exists in si. 

Strspn (strcspn) returns the length of the initial segment of string 
si which consists entirely of characters from (not from) string s2. 

Strtok considers the string si to consist of a sequence of zero or 
more text tokens separated by spans of one or more characters 
from the separator string s2. The first call (with pointer si 
specified) returns a pointer to the first character of the first token, 
and will have written a null character into si immediately follow- 
ing the returned token. The function keeps track of its position in 
the string between separate calls, so that subsequent calls (which 
must be made with the first argument a NULL pointer) will work 
through the string si immediately following that token. In this 
way subsequent calls will work through the string si until no 
tokens remain. The separator string s2 may be different from call 
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to call. When no token remains in si, a NULL pointer is returned. 

NOTE 

For user convenience, all these functions are declared in the 
optional <string.h> header file. 

BUGS 

Strcmp and strncmp use native character comparison, which is 
signed on most machines and unsigned on other machines. Thus 
the sign of the value returned when one of the characters has its 
high-order bit set is implementation-dependent. 

Character movement is performed differently in different imple- 
mentations. Thus overlapping moves may yield surprises. 
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NAME 

strtod, atof — convert string to double-precision number 

SYNOPSIS 

double strtod (str, ptr) 
char *str, **ptr; 

double atof (str) 
char *str; 

DESCRIPTION 

Strtod returns as a double-precision floating-point number the 
value represented by the character string pointed to by str. The 
string is scanned up to the first unrecognized character. 

Strtod recognizes an optional string of "white-space" characters 
(as defined by isspace in ctype(3C)), then an optional sign, then a 
string of digits optionally containing a decimal point, then an 
optional e or E followed by an optional sign or space, followed by 
an integer. 

If the value of ptr is not (char **)NULL, a pointer to the charac- 
ter terminating the scan is returned in the location pointed to by 
ptr. If no number can be formed, *ptr is set to str, and zero is 
returned. 

Atof (str) is equivalent to strtodistr, (char **)NULL). 

SEE ALSO 

ctypeOC), scanf(3S), strtol(3C). 

DIAGNOSTICS 

If the correct value would cause overflow, ±HUGE is returned 
(according to the sign of the value), and errno is set to ERANGE. 
If the correct value would cause underflow, zero is returned and 
errno is set to ERANGE. 
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NAME 

strtol, atol, atoi — convert string to integer 

SYNOPSIS 

long strtol (str, ptr, base) 
char *str, **ptr; 
int base; 

long atol (str) 
char *str; 

int atoi (str) 
char *str; 

DESCRIPTION 

Strtol returns as a long integer the value represented by the char- 
acter string pointed to by str. The string is scanned up to the first 
character inconsistent with the base. Leading "white-space" char- 
acters (as defined by isspace in ctypeOO) are ignored. 

If the value of ptr is not (char **)NULL, a pointer to the charac- 
ter terminating the scan is returned in the location pointed to by 
ptr. If no integer can be formed, that location is set to str, and 
zero is returned. 

If base is positive (and not greater than 36), it is used as the base 
for conversion. After an optional leading sign, leading zeros are 
ignored, and "Ox" or "OX" is ignored if base is 16. 

If base is zero, the string itself determines the base thusly: After 
an optional leading sign a leading zero indicates octal conversion, 
and a leading "Ox" or "OX" hexadecimal conversion. Otherwise, 
decimal conversion is used. 

Truncation from long to int can, of course, take place upon assign- 
ment or by an explicit cast. 

Atol(str) is equivalent to strtol(str, (char **)NULL, 10). 
Atoi (str) is equivalent to (int) strtol (str, (char **)NULL, 10). 

SEE ALSO 

ctypeOO, scanf(3S), strtod(3C). 

BUGS 

Overflow conditions are ignored. 
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NAME 

swab — swap bytes 

SYNOPSIS 

void swab (from, to, nbytes) 
char *from, *to; 
int nbytes; 

DESCRIPTION 

Swab copies nbytes bytes pointed to by from to the array pointed 
to by to, exchanging adjacent even and odd bytes. It is useful for 
carrying binary data between PDP-lls and other machines. 
Nbytes should be even and non-negative. If nbytes is odd and 
positive swab uses nbytes— I instead. If nbytes is negative, swab 
does nothing. 
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NAME 

tsearch, tfind, tdelete, twalk — manage binary search trees 

SYNOPSIS 

#include <search.h> 

char » tsearch ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tfind ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tdelete ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

void twalk ((char •) root, action) 
void (taction) ( ); 

DESCRIPTION 

Tsearch, tfind, tdelete, and twalk are routines for manipulating 
binary search trees. They are generalized from Knuth (6.2.2) 
Algorithms T and D. All comparisons are done with a user- 
supplied routine. This routine is called with two arguments, the 
pointers to the elements being compared. It returns an integer less 
than, equal to, or greater than 0, according to whether the first 
argument is to be considered less than, equal to or greater than the 
second argument. The comparison function need not compare 
every byte, so arbitrary data may be contained in the elements in 
addition to the values being compared. 

Tsearch is used to build and access the tree. Key is a pointer to a 
datum to be accessed or stored. If there is a datum in the tree 
equal to *key (the value pointed to by key), a pointer to this found 
datum is returned. Otherwise, *key is inserted, and a pointer to it 
returned. Only pointers are copied, so the calling routine must 
store the data. Rootp points to a variable that points to the root of 
the tree. A NULL value for the variable pointed to by rootp 
denotes an empty tree; in this case, the variable will be set to point 
to the datum which will be at the root of the new tree. 

Like tsearch, tfind will search for a datum in the tree, returning a 
pointer to it if found. However, if it is not found, tfind will return 
a NULL pointer. The arguments for tfind are the same as for 
tsearch. 

Tdelete deletes a node from a binary search tree. The arguments 
are the same as for tsearch. The variable pointed to by rootp will 
be changed if the deleted node was the root of the tree. Tdelete 
190— System Calls and Library Routines UNIX Programmer's Manual 



TSEARCHOC) 



TSEARCHOC) 



returns a pointer to the parent of the deleted node, or a NULL 
pointer if the node is not found. 

Twalk traverses a binary search tree. Root is the root of the tree 
to be traversed. (Any node in a tree may be used as the root for a 
walk below that node.) Action is the name of a routine to be 
invoked at each node. This routine is, in turn, called with three 
arguments. The first argument is the address of the node being 
visited. The second argument is a value from an enumeration data 
type typedef enum { preorder, postorder, endorder, leaf } VISIT; 
(defined in the < search .h> header file), depending on whether 
this is the first, second or third time that the node has been visited 
(during a depth-first, left-to-right traversal of the tree), or whether 
the node is a leaf. The third argument is the level of the node in 
the tree, with the root being level zero. 

The pointers to the key and the root of the tree should be of type 
pointer-to-element, and cast to type pointer-to-character. Simi- 
larly, although declared as type pointer-to-character, the value 
returned should be cast into type pointer-to-element. 

EXAMPLE 

The following code reads in strings and stores structures containing 
a pointer to each string and a count of its length. It then walks 
the tree, printing out the stored strings and their lengths in alpha- 
betical order. 

#include <search.h> 
#include <stdio.h> 

struct node { /* pointers to these are stored in the tree */ 

char *string; 
int length; 

}; 

char string_space[10000]; /* space to store strings */ 

struct node nodes! 500]; /* nodes to store */ 

struct node *root — NULL; /* this points to the root */ 

main( ) 
{ 

char *strptr — string space; 
struct node *nodeptr — nodes; 
void print_node( ), twalk ( ); 
int i «■ 0, node_compare( ); 
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while (gets(strptr) !- NULL && i++ < 500) { 
/♦set node ♦/ 
nodeptr— > string — strptr; 
nodeptr— > length — strlen (strptr); 
/♦ put node into the tree */ 
(void) tsearch((char *)nodeptr, &root, 

node_compare); 
/* adjust pointers, so we don't overwrite tree */ 
strptr +— nodeptr— > length + 1; 
nodeptr++; 

} 

twalk(root, printnode); 

} 

/* 

This routine compares two nodes, based on an 
alphabetical ordering of the string field. 

*/ 

int 

node compare (node 1 , node2) 
struct node *nodel, *node2; 
{ 

return strcmp(nodel-> string, node2-> string); 

} 

/* 

This routine prints out a node, the first time 
twalk encounters it. 

*/ 

void 

print_node(node, order, level) 

struct node **node; 

VISIT order; 

int level; 

{ 

if (order ™ preorder II order == leaf) { 

(void) printf ("string = %20s, length - %d\n", 
(♦node) — > string, (♦node) — > length) ; 

} 

} 

SEE ALSO 

bsearchOO, hsearch(3C), lsearch(3C). 
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DIAGNOSTICS 

A NULL pointer is returned by tsearch if there is not enough 
space available to create a new node. 

A NULL pointer is returned by tsearch, tfind and tdelete if rootp 
is NULL on entry. 

If the datum is found, both tsearch and tfind return a pointer to it. 
If not, tfind returns NULL, and tsearch returns a pointer to the 
inserted item. 

WARNINGS 

The root argument to twalk is one level of indirection less than 
the rootp arguments to tsearch and tdelete. 
There are two nomenclatures used to refer to the order in which 
tree nodes are visited. Tsearch uses preorder, postorder and 
endorder to respectively refer to visting a node before any of its 
children, after its left child and before its right, and after both its 
children. The alternate nomenclature uses preorder, inorder and 
postorder to refer to the same visits, which could result in some 
confusion over the meaning of postorder. 

BUGS 

If the calling function alters the pointer to the root, results are 
unpredictable. 
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NAME 

ttyname, isatty — find name of a terminal 

SYNOPSIS 

char *ttyname (tildes) 
int fildes; 

int isatty (fildes) 
int fildes; 

DESCRIPTION 

Ttyname returns a pointer to a string containing the null- 
terminated path name of the terminal device associated with file 
descriptor fildes. 

Isatty returns 1 if fildes is associated with a terminal device, 0 
otherwise. 

FILES 

. /dev/* 
DIAGNOSTICS 

Ttyname returns a NULL pointer if fildes does not describe a ter- 
minal device in directory /dev. 

BUGS 

The return value points to static data whose content is overwritten 
by each call. 
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NAME 

ttyslot — find the slot in the utmp file of the current user 

SYNOPSIS 

int ttyslot ( ) 

DESCRIPTION 

Ttyslot returns the index of the current user's entry in the 
/etc/utmp file. This is accomplished by actually scanning the file 
/etc/inittab for the name of the terminal associated with the stan- 
dard input, the standard output, or the error output (0, 1 or 2). 

FILES 

/etc/inittab 
/etc/utmp 

SEE ALSO 

getutOO, ttyname(3C). 

DIAGNOSTICS 

A value of 0 is returned if an error was encountered while search- 
ing for the terminal name or if none of the above file descriptors is 
associated with a terminal device. 
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NAME 

ctermid — generate file name for terminal 

SYNOPSIS 

#include <stdio.h> 
char *ctermid (s) 
char »s; 

DESCRIPTION 

Ctermid generates the path name of the controlling terminal for 
the current process, and stores it in a string. 

If s is a NULL pointer, the string is stored in an internal static 
area, the contents of which are overwritten at the next call to cter- 
mid, and the address of which is returned. Otherwise, s is 
assumed to point to a character array of at least L_ctermid ele- 
ments; the path name is placed in this array and the value of s is 
returned. The constant L_ctermid is defined in the <stdio.h> 
header file. 

NOTES 

The difference between ctermid and ttyname (30 is that ttyname 
must be handed a file descriptor and returns the actual name of 
the terminal associated with that file descriptor, while ctermid 
returns a string (/dev/tty) that will refer to the terminal if used as 
a file name. Thus ttyname is useful only if the process already has 
at least one file open to a terminal. 

SEE ALSO 

ttyname(3C). 
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NAME 

cuserid — get character login name of the user 

SYNOPSIS 

#include <stdio.h> 

char *cuserid (s) 
char *s; 

DESCRIPTION 

Cuserid generates a character-string representation of the login 
name that the owner of the current process is logged in under. If 
s is a NULL pointer, this representation is generated in an internal 
static area, the address of which is returned. Otherwise, s is 
assumed to point to an array of at least L_cuserid characters; the 
representation is left in this array. The constant L_cuserid is 
defined in the <stdio.h> header file. 

DIAGNOSTICS 

If the login name cannot be found, cuserid returns a NULL 
pointer; if s is not a NULL pointer, a null character (\0) will be 
placed at sfOj. 

SEE ALSO 

getlogin(3C), getpwent(3C). 
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NAME 

fclose, fflush — close or flush a stream 

SYNOPSIS 

#include <stdio.h> 

int fclose (stream) 
FILE *stream; 

int fflush (stream) 
FILE «stream; 

DESCRIPTION 

Fclose causes any buffered data for the named stream to be writ- 
ten out, and the stream to be closed. 

Fclose is performed automatically for all open files upon calling 
exit (2) . 

Fflush causes any buffered data for the named stream to be writ- 
ten to that file. The stream remains open. 

DIAGNOSTICS 

These functions return 0 for success, and EOF if any error (such as 
trying to write to a file that has not been opened for writing) was 
detected. 

SEE ALSO 

close (2), exit (2), fopen(3S), setbuf(3S). 
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NAME 

ferror, feof, clearerr, fileno — stream status inquiries 

SYNOPSIS 

#include <stdio.h> 

int ferror (stream) 
FILE 'stream; 

int feof (stream) 
FILE *stream; 

void clearerr (stream) 
FILE *stream; 

int fileno (stream) 
FILE *stream; 

DESCRIPTION 

Ferror returns non-zero when an I/O error has previously occurred 
reading from or writing to the named stream, otherwise zero. 

Feof returns non-zero when EOF has previously been detected 
reading the named input stream, otherwise zero. 

Clearerr resets the error indicator and EOF indicator to zero on 
the named stream. 

Fileno returns the integer file descriptor associated with the named 
stream ; see open (2). 

NOTE 

All these functions are implemented as macros; they cannot be 
declared or redeclared. 

SEE ALSO 

open (2), fopenOS). 
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NAME 

fopen, freopen, fdopen — open a stream 

SYNOPSIS 

#include <stdio.h> 

FILE *fopen (file-name, type) 
char *file-name, *type; 

FILE *freopen (file-name, type, stream) 
char ♦file-name, *type; 
FILE *stream; 

FILE *fdopen (fildes, type) 
int fildes; 
char *type; 

DESCRIPTION 

Fopen opens the file named by file-name and associates a stream 
with it. Fopen returns a pointer to the FILE structure associated 
with the stream. 

File-name points to a character string that contains the name of 
the file to be opened. 

Type is a character string having one of the following values: 

"r" open for reading 

"w" truncate or create for writing 

"a" append; open for writing at end of file, or 

create for writing 

"r+" open for update (reading and writing) 

"w+" truncate or create for update 

"a+" append; open or create for update at end-of-file 

Freopen substitutes the named file in place of the open stream. 
The original stream is closed, regardless of whether the open ulti- 
mately succeeds. Freopen returns a pointer to the FILE structure 
associated with stream. 

Freopen is typically used to attach the preopened streams associ- 
ated with stdin, stdout and stderr to other files. 
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Fdopen associates a stream with a file descriptor. File descriptors 
are obtained from open, dup, creat, or piped), which open files 
but do not return pointers to a FILE structure stream. Streams are 
necessary input for many of the Section 3S library routines. The 
type of stream must agree with the mode of the open file. 

When a file is opened for update, both input and output may be 
done on the resulting stream. However, output may not be 
directly followed by input without an intervening fseek or rewind, 
and input may not be directly followed by output without an inter- 
vening fseek, rewind, or an input operation which encounters end- 
of-file. 

When a file is opened for append (i.e., when type is "a" or "a+"), it 
is impossible to overwrite information already in the file. Fseek 
may be used to reposition the file pointer to any position in the file, 
but when output is written to the file, the current file pointer is 
disregarded. All output is written at the end of the file and causes 
the file pointer to be repositioned at the end of the output. If two 
separate processes open the same file for append, each process may 
write freely to the file without fear of destroying output being writ- 
ten by the other. The output from the two processes will be inter- 
mixed in the file in the order in which it is written. 

SEE ALSO 

creat(2), dup(2), open(2), pipe(2), fclose(3S), fseek(3S). 

DIAGNOSTICS 

Fopen and freopen return a NULL pointer on failure. 
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NAME 

fread, fwrite — binary input/output 

SYNOPSIS 

#include <stdio.h> 

int fread (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE *stream; 

int fwrite (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE *stream; 

DESCRIPTION 

Fread copies, into an array pointed to by ptr, nitems items of data 
from the named input stream, where an item of data is a sequence 
of bytes (not necessarily terminated by a null byte) of length size. 
Fread stops appending bytes if an end-of-file or error condition is 
encountered while reading stream, or if nitems items have been 
read. Fread leaves the file pointer in stream, if defined, pointing 
to the byte following the last byte read if there is one. Fread does 
not change the contents of stream . 

Fwrite appends at most nitems items of data from the array 
pointed to by ptr to the named output stream. Fwrite stops 
appending when it has appended nitems items of data or if an 
error condition is encountered on stream. Fwrite does not change 
the contents of the array pointed to by ptr. 

The argument size is typically sizeof(*ptr) where the pseudo- 
function sizeof specifies the length of an item pointed to by ptr. If 
ptr points to a data type other than char it should be cast into a 
pointer to char. 

SEE ALSO 

read (2), write (2), fopen(3S), getc(3S), gets(3S), printf(3S), 
putc(3S), puts(3S), scanfOS). 

DIAGNOSTICS 

Fread and fwrite return the number of items read or written. If 
size or nitems is non-positive, no characters are read or written 
and 0 is returned by both fread and fwrite. 
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NAME 

fseek, rewind, ftell — reposition a file pointer in a stream 

SYNOPSIS 

#include <stdio.h> 

int fseek (stream, offset, ptrname) 
FILE *stream; 
long offset; 
int ptrname; 

void rewind (stream) 
FILE *stream; 

long ftell (stream) 
FILE *stream; 

DESCRIPTION 

Fseek sets the position of the next input or output operation on the 
stream. The new position is at the signed distance offset bytes 
from the beginning, from the current position, or from the end of 
the file, according as ptrname has the value 0, 1, or 2. 

Rewind {stream) is equivalent to fseek {stream, 0L, 0), except that 
no value is returned. 

Fseek and rewind undo any effects of ungetc (3S). 

After fseek or rewind, the next operation on a file opened for 
update may be either input or output. 

Ftell returns the offset of the current byte relative to the beginning 
of the file associated with the named stream. 

SEE ALSO 

lseek(2), fopenOS), popen(3S), ungetc(3S). 

DIAGNOSTICS 

Fseek returns non-zero for improper seeks, otherwise zero. An 
improper seek can be, for example, an fseek done on a file that has 
not been opened via fopen; in particular, fseek may not be used on 
a terminal, or on a file opened via popen (3S) . 

WARNING 

Although on the UNIX system an offset returned by ftell is meas- 
ured in bytes, and it is permissible to seek to positions relative to 
that offset, portability to non-UNIX systems requires that an offset 
be used by fseek directly. Arithmetic may not meaningfully be 
performed on such an offset. 
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NAME 

getc, getchar, fgetc, getw — get character or word from a stream 

SYNOPSIS 

#include <stdio.h> 

int getc (stream) 
FILE *stream; 

int getchar 0 

int fgetc (stream) 
FILE *stream; 

int getw (stream) 
FILE *stream; 

DESCRIPTION 

Getc returns the next character (i.e., byte) from the named input 
stream, as an integer. It also moves the file pointer, if defined, 
ahead one character in stream. Getchar is defined as getc(stdin) . 
Getc and getchar are macros. 

Fgetc behaves like getc, but is a function rather than a macro. 
Fgetc runs more slowly than getc, but it takes less space per invo- 
cation and its name can be passed as an argument to a function. 

Getw returns the next word (i.e., integer) from the named input 
stream. Getw increments the associated file pointer, if defined, to 
point to the next word. The size of a word is the size of an integer 
and varies from machine to machine. Getw assumes no special 
alignment in the file. 

SEE ALSO 

fclose(3S), ferrorOS), fopenOS), fread(3S), gets(3S), putc(3S), 
scanfOS). 

DIAGNOSTICS 

These functions return the constant EOF at end-of-file or upon an 
error. Because EOF is a valid integer, f error (3S) should be used 
to detect getw errors. 

WARNING 

If the integer value returned by getc, getchar, or fgetc is stored 
into a character variable and then compared against the integer 
constant EOF, the comparison may never succeed, because sign- 
extension of a character on widening to integer is machine- 
dependent. 
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BUGS 

Because it is implemented as a macro, getc treats incorrectly a 
stream argument with side effects. In particular, getc(*f++) does 
not work sensibly. Fgetc should be used instead. 
Because of possible differences in word length and byte ordering, 
files written using putw are machine-dependent, and may not be 
read using getw on a different processor. 
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NAME 

gets, fgets — get a string from a stream 

SYNOPSIS 

#include <stdio.h> 

char »gets (s) 
char *s; 

char *fgets (s, n, stream) 
char *s; 
int n; 

FILE *stream; 
DESCRIPTION 

Gets reads characters from the standard input stream, stdin, into 
the array pointed to by 5, until a new-line character is read or an 
end-of-file condition is encountered. The new-line character is dis- 
carded and the string is terminated with a null character. 

Fgets reads characters from the stream into the array pointed to 
by s, until n— 1 characters are read, or a new-line character is read 
and transferred to s, or an end-of-file condition is encountered. 
The string is then terminated with a null character. 

SEE ALSO 

ferrorOS), fopen(3S), fread(3S), getc(3S), scanfOS). 
DIAGNOSTICS 

If end-of-file is encountered and no characters have been read, no 
characters are transferred to s and a NULL pointer is returned. If 
a read error occurs, such as trying to use these functions on a file 
that has not been opened for reading, a NULL pointer is returned. 
Otherwise s is returned. 



UNIX Programmer's Manual System Calls and Library Routines— 207 



POPENOS) 



POPENOS) 



NAME 

popen, pclose — initiate pipe to/from a process 

SYNOPSIS 

#include <stdio.h> 

FILE * popen (command, type) 
char 'command, *type; 

int pclose (stream) 
FILE *stream; 

DESCRIPTION 

The arguments to popen are pointers to null-terminated strings 
containing, respectively, a shell command line and an I/O mode, 
either r for reading or w for writing. Popen creates a pipe 
between the calling program and the command to be executed. 
The value returned is a stream pointer such that one can write to 
the standard input of the command, if the I/O mode is w, by writ- 
ing to the file stream; and one can read from the standard output 
of the command, if the I/O mode is r, by reading from the file 
stream . 

A stream opened by popen should be closed by pclose, which waits 
for the associated process to terminate and returns the exit status 
of the command. 

Because open files are shared, a type r command may be used as 
an input filter and a type w as an output filter. 

SEE ALSO 

pipe (2), wait (2), fclose(3S), fopen(3S), system (3S). 
DIAGNOSTICS 

Popen returns a NULL pointer if files or processes cannot be 
created, or if the shell cannot be accessed. 

Pclose returns —1 if stream is not associated with a "popen ed" 
command. 

BUGS 

If the original and "popen ed" processes concurrently read or write 
a common file, neither should use buffered I/O, because the 
buffering gets all mixed up. Problems with an output filter may be 
forestalled by careful buffer flushing, e.g. with fflush; see 
/close OS). 
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NAME 

printf, fprintf, sprintf — print formatted output 

SYNOPSIS 

#include <stdio.h> 

int printf (format [ , arg ] ... ) 
char *format; 

int fprintf (stream, format [ , arg ] . . . ) 
FILE *stream; 
char *format; 

int sprintf (s, format [ , arg ] ... ) 
char *s, format; 

DESCRIPTION 

Printf places output on the standard output stream stdout. 
Fprintf places output on the named output stream. Sprintf places 
"output," followed by the null character (\0), in consecutive bytes 
starting at *s; it is the user's responsibility to ensure that enough 
storage is available. Each function returns the number of charac- 
ters transmitted (not including the \0 in the case of sprintf), or a 
negative value if an output error was encountered. 

Each of these functions converts, formats, and prints its args under 
control of the format. The format is a character string that con- 
tains two types of objects: plain characters, which are simply 
copied to the output stream, and conversion specifications, each of 
which results in fetching of zero or more args. The results are 
undefined if there are insufficient args for the format. If the for- 
mat is exhausted while args remain, the excess args are simply 
ignored. 

Each conversion specification is introduced by the character %. 
After the % , the following appear in sequence: 

Zero or more flags, which modify the meaning of the 
conversion specification. 

An optional decimal digit string specifying a minimum 
field width. If the converted value has fewer characters 
than the field width, it will be padded on the left (or right, 
if the left-adjustment flag '— ', described below, has been 
given) to the field width. If the field width for an s 
conversion is preceded by a 0, the string is right adjusted 
with zero-padding on the left. 
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A precision that gives the minimum number of digits to 
appear for the d, o, u, x, or X conversions, the number of 
digits to appear after the decimal point for the e and f 
conversions, the maximum number of significant digits for 
the g conversion, or the maximum number of characters to 
be printed from a string in s conversion. The precision 
takes the form of a period (.) followed by a decimal digit 
string; a null digit string is treated as zero. 

An optional 1 (ell) specifying that a following d, o, u, x, or 
X conversion character applies to a long integer arg. A 1 
before any other conversion character is ignored. 

A character that indicates the type of conversion to be 
applied. 

A field width or precision may be indicated by an asterisk (*) 
instead of a digit string. In this case, an integer arg supplies the 
field width or precision. The arg that is actually converted is not 
fetched until the conversion letter is seen, so the args specifying 
field width or precision must appear before the arg (if any) to be 
converted. 

The flag characters and their meanings are: 
— The result of the conversion will be left-justified within 

the field. 

+ The result of a signed conversion will always begin 

with a sign ( + or — ) . 

blank If the first character of a signed conversion is not a 
sign, a blank will be prefixed to the result. This 
implies that if the blank and + flags both appear, the 
blank flag will be ignored. 

# This flag specifies that the value is to be converted to 

an "alternate form." For c, d, s, and u conversions, the 
flag has no effect. For o conversion, it increases the 
precision to force the first digit of the result to be a 
zero. For x or X conversion, a non-zero result will 
have Ox or OX prefixed to it. For e, E, f, g, and G 
conversions, the result will always contain a decimal 
point, even if no digits follow the point (normally, a 
decimal point appears in the result of these conversions 
only if a digit follows it). For g and G conversions, 
trailing zeroes will not be removed from the result 
(which they normally are). 
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The conversion characters and their meanings are: 

d, o,u,x,x The integer arg is converted to signed decimal, 

unsigned octal, decimal, or hexadecimal notation (x 
and X), respectively; the letters abcdef are used for x 
conversion and the letters ABCDEF for X conversion. 
The precision specifies the minimum number of digits 
to appear; if the value being converted can be 
represented in fewer digits, it will be expanded with 
leading zeroes. (For compatibility with older versions, 
padding with leading zeroes may alternatively be 
specified by prepending a zero to the field width. This 
does not imply an octal value for the field width.) The 
default precision is 1. The result of converting a zero 
value with a precision of zero is a null string, 
f The float or double arg is converted to decimal nota- 

tion in the style "[ — Iddd.ddd," where the number of 
digits after the decimal point is equal to the precision 
specification. If the precision is missing, six digits are 
output; if the precision is explicitly 0, no decimal point 
appears. 

e, E The float or double arg is converted in the style 

"[ — ]d.ddde±dd," where there is one digit before the 
decimal point and the number of digits after it is equal 
to the precision; when the precision is missing, six 
digits are produced; if the precision is zero, no decimal 
point appears. The E format code will produce a 
number with E instead of e introducing the exponent. 
The exponent always contains at least two digits. 

g,G The float or double arg is printed in style f or e (or in 

style E in the case of a G format code), with the preci- 
sion specifying the number of significant digits. The 
style used depends on the value converted: style e will 
be used only if the exponent resulting from the conver- 
sion is less than —4 or greater than the precision. 
Trailing zeroes are removed from the result; a decimal 
point appears only if it is followed by a digit. 

c The character arg is printed. 

s The arg is taken to be a string (character pointer) and 

characters from the string are printed until a null char- 
acter (\0) is encountered or the number of characters 
indicated by the precision specification is reached. If 
the precision is missing, it is taken to be infinite, so all 
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characters up to the first null character are printed. A 
NULL value for arg will yield undefined results. 
% Print a % ; no argument is converted. 

In no case does a non-existent or small field width cause truncation 
of a field; if the result of a conversion is wider than the field width, 
the field is simply expanded to contain the conversion result. 
Characters generated by printf and fprintf are printed as if 
putc (3S) had been called. 

EXAMPLES 

To print a date and time in the form "Sunday, July 3, 10:02," 
where weekday and month are pointers to null-terminated strings: 

printf ("%s, %s %d, %d:%.2d", weekday, month, day, hour, min); 

To print tt to 5 decimal places: 

printfC'pi - %.5f", 4 * atan(l.O)); 

SEE ALSO 

ecvt(3C), putc(3S), scanf(3S), stdio(3S). 
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NAME 

putc, putchar, fputc, putw — put character or word on a stream 

SYNOPSIS 

#include <stdio.h> 

int putc (c, stream) 
int c; 

FILE ♦stream; 

int putchar (c) 
int c; 

int fputc (c, stream) 
int c; 

FILE ♦stream; 

int putw (w, stream) 
int w; 

FILE ♦stream; 
DESCRIPTION 

Putc writes the character c onto the output stream (at the position 
where the file pointer, if defined, is pointing). Putchar (c) is 
defined as putcic, stdout). Putc and putchar are macros. 

Fputc behaves like putc, but is a function rather than a macro. 
Fputc runs more slowly than putc, but it takes less space per invo- 
cation and its name can be passed as an argument to a function. 

Putw writes the word (i.e. integer) w to the output stream (at the 
position at which the file pointer, if defined, is pointing). The size 
of a word is the size of an integer and varies from machine to 
machine. Putw neither assumes nor causes special alignment in 
the file. 

Output streams, with the exception of the standard error stream 
stderr, are by default buffered if the output refers to a file and 
line-buffered if the output refers to a terminal. The standard error 
output stream stderr is by default unbuffered, but use of freopen 
(see fopen (3S)) will cause it to become buffered or line-buffered. 

When an output stream is unbuffered, information is queued for 
writing on the destination file or terminal as soon as written; when 
it is buffered, many characters are saved up and written as a 
block. When it is line-buffered, each line of output is queued for 
writing on the destination terminal as soon as the line is completed 
(that is, as soon as a new-line character is written or terminal 
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input is requested). Setbuf (3S) or Setbuj (3S) may be used to 
change the stream's buffering strategy. 

SEE ALSO 

fclose(3S), ferrorOS), fopen(3S), fread(3S), printf(3S), puts(3S), 
setbuf (3S). 

DIAGNOSTICS 

On success, these functions each return the value they have writ- 
ten. On failure, they return the constant EOF. This will occur if 
the file stream is not open for writing or if the output file cannot 
be grown. Because EOF is a valid integer, ferror (3S) should be 
used to detect putw errors. 

BUGS 

Because it is implemented as a macro, putc treats incorrectly a 
stream argument with side effects. In particular, putcCc, *f++); 
doesn't work sensibly. Fputc should be used instead. 
Because of possible differences in word length and byte ordering, 
files written using putw are machine-dependent, and may not be 
read using getw on a different processor. 
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NAME 

puts, fputs — put a string on a stream 

SYNOPSIS 

#include <stdio.h> 

int puts (s) 
char *s; 

int fputs (s, stream) 
char *s; 
FILE *stream; 

DESCRIPTION 

Puts writes the null-terminated string pointed to by s, followed by 
a new-line character, to the standard output stream stdout. 

Fputs writes the null-terminated string pointed to by s to the 
named output stream. 

Neither function writes the terminating null character. 
DIAGNOSTICS 

Both routines return EOF on error. This will happen if the routines 
try to write on a file that has not been opened for writing. 

SEE ALSO 

ferrorOS), fopenOS), fread(3S), printf(3S), putc(3S). 

NOTES 

Puts appends a new-line character while fputs does not. 
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scanf, fscanf, sscanf — convert formatted input 

SYNOPSIS 

#include <stdio.h> 

int scanf (format [ , pointer ] ... ) 
char *format; 

int fscanf (stream, format [ , pointer ] ... ) 
FILE *stream; 
char 'format; 

int sscanf (s, format [ , pointer ] . . . ) 
char *s, *format; 

DESCRIPTION 

Scanf reads from the standard input stream stdin. Fscanf reads 
from the named input stream. Sscanf reads from the character 
string s. Each function reads characters, interprets them accord- 
ing to a format, and stores the results in its arguments. Each 
expects, as arguments, a control string format described below, 
and a set of pointer arguments indicating where the converted 
input should be stored. 

The control string usually contains conversion specifications, which 
are used to direct interpretation of input sequences. The control 
string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form-feeds) 
which, except in two cases described below, cause input to be 
read up to the next non-white-space character. 

2. An ordinary character (not %), which must match the next 
character of the input stream. 

3. Conversion specifications, consisting of the character %, an 
optional assignment suppressing character *, an optional 
numerical maximum field width, an optional 1 (ell) or h indi- 
cating the size of the receiving variable, and a conversion code. 

A conversion specification directs the conversion of the next input 
field; the result is placed in the variable pointed to by the 
corresponding argument, unless assignment suppression was indi- 
cated by *. The suppression of assignment provides a way of 
describing an input field which is to be skipped. 

An input field is defined as a string of non-space characters; it 
extends to the next inappropriate character or until the field width, 
if specified, is exhausted. For all descriptors except "[" and "c", 
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white space leading an input field is ignored. 

The conversion code indicates the interpretation of the input field; 
the corresponding pointer argument must usually be of a restricted 
type. For a suppressed field, no pointer argument is given. The 
following conversion codes are legal: 

% a single % is expected in the input at this point; no 

assignment is done, 
d a decimal integer is expected; the corresponding argument 

should be an integer pointer, 
u an unsigned decimal integer is expected; the corresponding 

argument should be an unsigned integer pointer. 

0 an octal integer is expected; the corresponding argument 
should be an integer pointer. 

x a hexadecimal integer is expected; the corresponding argu- 
ment should be an integer pointer. 

e,f,g a floating point number is expected; the next field is con- 
verted accordingly and stored through the corresponding 
argument, which should be a pointer to a float. The input 
format for floating point numbers is an optionally signed 
string of digits, possibly containing a decimal point, fol- 
lowed by an optional exponent field consisting of an E or 
an e, followed by an optional +, — , or space, followed by 
an integer. 

s a character string is expected; the corresponding argument 

should be a character pointer pointing to an array of char- 
acters large enough to accept the string and a terminating 
\0, which will be added automatically. The input field is 
terminated by a white-space character. 

c a character is expected; the corresponding argument 
should be a character pointer. The normal skip over white 
space is suppressed in this case; to read the next non-space 
character, use %ls. If a field width is given, the 
corresponding argument should refer to a character array; 
the indicated number of characters is read. 

1 indicates string data and the normal skip over leading 
white space is suppressed. The left bracket is followed by 
a set of characters, which we will call the scanset, and a 
right bracket; the input field is the maximal sequence of 
input characters consisting entirely of characters in the 
scanset. The circumflex (*), when it appears as the first 
character in the scanset, serves as a complement operator 
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and redefines the scanset as the set of all characters not 
contained in the remainder of the scanset string. There 
are some conventions used in the construction of the scan- 
set. A range of characters may be represented by the con- 
struct first— last, thus [0123456789] may be expressed 
[0—9]. Using this convention, first must be lexically less 
than or equal to last, or else the dash will stand for itself. 
The dash will also stand for itself whenever it is the first 
or the last character in the scanset. To include the right 
square bracket as an element of the scanset, it must 
appear as the first character (possibly preceded by a 
circumflex) of the scanset, and in this case it will not be 
syntactically interpreted as the closing bracket. The 
corresponding argument must point to a character array 
large enough to hold the data field and the terminating \0, 
which will be added automatically. At least one character 
must match for this conversion to be considered successful. 

The conversion characters d, u, o, and x may be preceded by 1 or h 
to indicate that a pointer to long or to short rather than to int is in 
the argument list. Similarly, the conversion characters e, f, and g 
may be preceded by 1 to indicate that a pointer to double rather 
than to float is in the argument list. The 1 or h modifier is ignored 
for other conversion characters. 

Scanf conversion terminates at EOF, at the end of the control 
string, or when an input character conflicts with the control string. 
In the latter case, the offending character is left unread in the 
input stream. 

Scanf returns the number of successfully matched and assigned 
input items; this number can be zero in the event of an early 
conflict between an input character and the control string. If the 
input ends before the first conflict or conversion, EOF is returned. 

EXAMPLES 

The call: 

int i, n; float x; char name[50]; 

n - scanf ("%d%f%s", &i, &x, name); 

with the input line: 

25 54.32E-1 thompson 

will assign to n the value 3, to i the value 25, to x the value 5.432, 
and name will contain thompson\0. Or: 
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int i; float x; char name[50]; 

(void) scanf ("%2d%f%*d %[0-9]", &i, &x, name); 

with input: 

56789 0123 56a72 

will assign 56 to i, 789.0 to x, skip 0123, and place the string 56\0 
in name. The next call to getchar (see getc (3S)) will return a. 

SEE ALSO 

getc(3S), printf(3S), strtod(3C), strtol(3C). 

NOTE 

Trailing white space (including a new-line) is left unread unless 
matched in the control string. 

DIAGNOSTICS 

These functions return EOF on end of input and a short count for 
missing or illegal data items. 

BUGS 

The success of literal matches and suppressed assignments is not 
directly determinable. 
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NAME 

setbuf, setvbuf — assign buffering to a stream 

SYNOPSIS 

#include <stdio.h> 

void setbuf (stream, buf) 
FILE *stream; 
char *buf; 

int setvbuf (stream, buf, type, size) 
FILE *stream; 
char *buf; 
int type, size; 

DESCRIPTION 

Setbuf may be used after a stream has been opened but before it 
is read or written. It causes the array pointed to by buf to be used 
instead of an automatically allocated buffer. If buf is the NULL 
pointer input/output will be completely unbuffered. 

A constant BUFSIZ, defined in the <stdio.h> header file, tells 
how big an array is needed: 

char buflBUFSIZ]; 

Setvbuf may be used after a stream has been opened but before it 
is read or written. Type determines how stream will be buffered. 
Legal values for type (defined in stdio.h) are: 

IOFBF causes input/output to be fully buffered. 

IOLBF causes output to be line buffered; the buffer will be 
flushed when a newline is written, the buffer is full, 
or input is requested. 

_IONBF causes input/output to be completely unbuffered. 

If buf is not the NULL pointer, the array it points to will be used 
for buffering, instead of an automatically allocated buffer. Size 
specifies the size of the buffer to be used. The constant BUFSIZ in 
< stdio.h > is suggested as a good buffer size. If input/output is 
unbuffered, buf and size are ignored. 

By default, output to a terminal is line buffered and all other 
input/output is fully buffered. 

SEE ALSO 

fopenOS), getcOS), mallocOO, putc(3S), stdio(3S). 
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DIAGNOSTICS 

If an illegal value for type or size is provided, setvbuf returns a 
non-zero value. Otherwise, the value returned will be zero. 

NOTE 

A common source of error is allocating buffer space as an 
"automatic" variable in a code block, and then failing to close the 
stream in the same block. 
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NAME 

stdio — standard buffered input/output package 

SYNOPSIS 

#include <stdio.h> 

FILE *stdin, *stdout, *stderr; 

DESCRIPTION 

The functions described in the entries of sub-class 3S of this 
manual constitute an efficient, user-level I/O buffering scheme. 
The in-line macros getc(3S) and putc(3S) handle characters 
quickly. The macros getchar and putchar, and the higher-level 
routines fgetc, fgets, fprintf, fputc, fputs, fread, fscanf, /write, 
gets, getw, printf, puts, putw, and scanf all use or act as if they 
use getc and putc; they can be freely intermixed. 

A file with associated buffering is called a stream and is declared 
to be a pointer to a defined type FILE. Fopen (3S) creates certain 
descriptive data for a stream and returns a pointer to designate the 
stream in all further transactions. Normally, there are three open 
streams with constant pointers declared in the <stdio.h> header 
file and associated with the standard open files: 

stdin standard input file 
stdout standard output file 
stderr standard error file 

A constant NULL (0) designates a nonexistent pointer. 

An integer-constant EOF (—1) is returned upon end-of-file or error 
by most integer functions that deal with streams (see the indivi- 
dual descriptions for details). 

An integer constant BUFSIZ specifies the size of the buffers used 
by the particular implementation. 

Any program that uses this package must include the header file 
of pertinent macro definitions, as follows: 

#include <stdio.h> 

The functions and constants mentioned in the entries of sub- 
class 3S of this manual are declared in that header file and need 
no further declaration. The constants and the following "func- 
tions" are implemented as macros (redeclaration of these names is 
perilous): getc, getchar, putc, putchar, /error, feof, clearerr, and 
fileno. 
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SEE ALSO 

open (2), close (2), lseek(2), pipe (2), read (2), write (2), 
ctermid(3S), cuserid(3S), fclose(3S), ferror(3S), fopen(3S), 
fread(3S), fseek(3S), getc(3S), gets(3S), popen(3S), printf(3S), 
putc(3S), puts(3S), scanf(3S), setbuf(3S), system(3S), 
tmpfile(3S), tmpnam(3S), ungetc(3S). 

DIAGNOSTICS 

Invalid stream pointers will usually cause grave disorder, possibly 
including program termination. Individual function descriptions 
describe the possible error conditions. 
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NAME 

system — issue a shell command 

SYNOPSIS 

#include <stdio.h> 

int system (string) 
char *string; 

DESCRIPTION 

System causes the string to be given to sh(l) as input, as if the 
string had been typed as a command at a terminal. The current 
process waits until the shell has completed, then returns the exit 
status of the shell. 

FILES 

/bin/sh 

SEE ALSO 

exec (2). 

sh(l) in the UNIX Programmer's Manual —Volume 1: Commands 
and Utilities. 

DIAGNOSTICS 

System forks to create a child process that in turn exec's /bin/sh 
in order to execute string. If the fork or exec fails, system returns 
a negative value and sets errno. 
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NAME 

tmpfile — create a temporary file 

SYNOPSIS 

#include <stdio.h> 

FILE *tmpfile () 

DESCRIPTION 

Tmpfile creates a temporary file using a name generated by 
tmpnamOS), and returns a corresponding FILE pointer. If the file 
cannot be opened, an error message is printed using perror (3C), 
and a NULL pointer is returned. The file will automatically be 
deleted when the process using it terminates. The file is opened 
for update ("w+"). 

SEE ALSO 

creat(2), unlink(2), fopen(3S), mktempOO, perror(3C), 
tmpnam(3S). 
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NAME 

tmpnam, tempnam — create a name for a temporary file 

SYNOPSIS 

#include <stdio.h> 

char * tmpnam (s) 
char *s; 

char * tempnam (dir, pfx) 
char »dir, *pfx; 

DESCRIPTION 

These functions generate file names that can safely be used for a 
temporary file. 

Tmpnam always generates a file name using the path-prefix 
defined as Pjtmpdir in the <stdio.h> header file. If s is NULL, 
tmpnam leaves its result in an internal static area and returns a 
pointer to that area. The next call to tmpnam will destroy the 
contents of the area. If s is not NULL, it is assumed to be the 
address of an array of at least Ltmpnam bytes, where Ltmpnam 
is a constant defined in <stdioh>; tmpnam places its result in 
that array and returns s. 

Tempnam allows the user to control the choice of a directory. The 
argument dir points to the name of the directory in which the file 
is to be created. If dir is NULL or points to a string which is not 
a name for an appropriate directory, the path-prefix defined as 
P_tmpdir in the <stdio.h> header file is used. If that directory is 
not accessible, /tmp will be used as a last resort. This entire 
sequence can be up-staged by providing an environment variable 
TMPDIR in the user's environment, whose value is the name of the 
desired temporary-file directory. 

Many applications prefer their temporary files to have certain 
favorite initial letter sequences in their names. Use the pfx argu- 
ment for this. This argument may be NULL or point to a string of 
up to five characters to be used as the first few characters of the 
temporary-file name. 

Tempnam uses malloc (3C) to get space for the constructed file 
name, and returns a pointer to this area. Thus, any pointer value 
returned from tempnam may serve as an argument to free (see 
malloc (3C)). 
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If tempnam cannot return the expected result for any reason, i.e. 
malloc(3C) failed, or none of the above mentioned attempts to 
find an appropriate directory was successful, a NULL pointer will 
be returned. 

NOTES 

These functions generate a different file name each time they are 
called. 

Files created using these functions and either fopenOS) or 
creat(2) are temporary only in the sense that they reside in a 
directory intended for temporary use, and their names are unique. 
It is the user's responsibility to use unlink (2) to remove the file 
when its use is ended. 

SEE ALSO 

creat(2), unlink(2), fopen(3S), malloc(3C), mktempOO, 
tmpfileOS). 

BUGS 

If called more than 17,576 times in a single process, these func- 
tions will start recycling previously used names. 
Between the time a file name is created and the file is opened, it is 
possible for some other process to create a file with the same 
name. This can never happen if that other process is using these 
functions or mktemp, and the file names are chosen so as to render 
duplication by other means unlikely. 
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NAME 

ungetc — push character back into input stream 

SYNOPSIS 

#include <stdio.h> 

int ungetc (c, stream) 
int c; 

FILE *stream; 
DESCRIPTION 

Ungetc inserts the character c into the buffer associated with an 
input stream. That character, c, will be returned by the next 
getcGS) call on that stream. Ungetc returns c, and leaves the file 
stream unchanged. 

One character of pushback is guaranteed, provided something has 
already been read from the stream and the stream is actually 
buffered. In the case that stream is stdin, one character may be 
pushed back onto the buffer without a previous read statement. 

If c equals EOF, ungetc does nothing to the buffer and returns 
EOF. 

Fseek (3S) erases all memory of inserted characters. 

SEE ALSO 

fseek (3S), getc(3S), setbuf(3S). 

DIAGNOSTICS 

Ungetc returns EOF if it cannot insert the character. 
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NAME 

vprintf, vfprintf, vsprintf — print formatted output of a varargs 
argument list 

SYNOPSIS 

#include <stdio.h> 
#include <varargs.h> 

int vprintf (format, ap) 
char *format; 
valist ap; 

int vfprintf (stream, format, ap) 
FILE *stream; 
char *format; 
va list ap; 

int vsprintf (s, format, ap) 
char *s, *format; 
vajist ap; 

DESCRIPTION 

vprintf, vfprintf, and vsprintf are the same as printf, fprintf, and 
sprintf respectively, except that instead of being called with a vari- 
able number of arguments, they are called with an argument list 
as defined by varargs (5). 

EXAMPLE 

The following demonstrates how vfprintf could be used to write an 
error routine. 

#include <stdio.h> 
#include <varargs.h> 



/* 

* error should be called like 

* error (functionname, format, argl, arg2...); 
*/ 

/♦VARARGSO*/ 
void 

error (vaalist) 

/* Note the function_name and format arguments cannot be 

* separately declared because of the definition of varargs. 
*/ 
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va list args; 
char *fmt; 

vastart(args); 

/* print out name of function causing error */ 
(void)fprintf(stderr, "ERROR in %s: ", va_arg(args, char •)); 
fmt = va_arg(args, char *); 
/* print out remainder of message */ 
(void)vfprintf(fmt, args); 
vaend(args); 
(void) abort ( ); 
} 

SEE ALSO 

vprintf(3X), varargs(5). 



vadcl 
{ 
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NAME 

jO, jl, jn, yO, yl, yn — Bessel functions 

SYNOPSIS 

#include <math.h> 

double jO (x) 
double x; 

double jl (x) 
double x; 

double jn (n, x) 
int n; 
double x; 

double yO (x) 
double x; 

double yl (x) 
double x; 

double yn (n, x) 
int n; 
double x; 

DESCRIPTION 

JO and jl return Bessel functions of x of the first kind of orders 0 
and 1 respectively. Jn returns the Bessel function of x of the first 
kind of order n. 

YO and yl return Bessel functions of x of the second kind of ord- 
ers 0 and 1 respectively. Yn returns the Bessel function of x of 
the second kind of order n. The value of x must be positive. 

DIAGNOSTICS 

Non-positive arguments cause yO, yl and yn to return the value 
-HUGE and to set errno to EDOM. In addition, a message indi- 
cating DOMAIN error is printed on the standard error output. 

Arguments too large in magnitude cause jO, jl, yO and yl to 
return zero and to set errno to ERANGE. In addition, a message 
indicating TLOSS error is printed on the standard error output. 

These error-handling procedures may be changed with the function 
matherr (3M). 

SEE ALSO 

matherr (3 M). 
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NAME 



erf, erfc — error function and complementary error function 



#include <math.h> 

double erf (x) 
double x; 

double erfc (x) 
double x; 



DESCRIPTION 



L C 2 

Erf returns the error function of x, defined as — —J e~* dt. 



Erfc, which returns 1.0 — erf(x), is provided because of the 
extreme loss of relative accuracy if erf(x) is called for large x and 
the result subtracted from 1.0 (e.g., for x = 5, 12 places are lost). 



SYNOPSIS 




SEE ALSO 



exp(3M). 
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NAME 

exp, log, log 10, pow, sqrt — exponential, logarithm, power, square 
root functions 



SYNOPSIS 




#include <math.h> 


double 


exp (x) 


double 


x; 


double 


log (x) 


double 


x; 


double 


loglO (x) 


double 


x; 


double 


pow (x, y) 


double 


x, y; 


double 


sqrt (x) 


double 


x; 


DESCRIPTION 



Exp returns e x . 

Log returns the natural logarithm of x. The value of x must be 
positive. 

LoglO returns the logarithm base ten of x. The value of x must 
be positive. 

Pow returns x? . If x is zero, y must be positive. If x is negative, 
y must be an integer. 

Sqrt returns the non-negative square root of x. The value of x 
may not be negative. 

DIAGNOSTICS 

Exp returns HUGE when the correct value would overflow, or 0 
when the correct value would underflow, and sets errno to 
ERANGE. 

Log and loglO return -HUGE and set errno to EDOM when x is 
non-positive. A message indicating DOMAIN error (or SING error 
when x is 0) is printed on the standard error output. 

Pow returns 0 and sets errno to EDOM when x is 0 and y is non- 
positive, or when x is negative and y is not an integer. In these 
cases a message indicating DOMAIN error is printed on the stan- 
dard error output. 
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When the correct value for paw would overflow or underflow, paw 
returns ±HUGE or 0 respectively, and sets errno to ERANGE. 

Sqrt returns 0 and sets errno to EDOM when x is negative. A 
message indicating DOMAIN error is printed on the standard error 
output. 

These error-handling procedures may be changed with the function 
matherr(3M). 

SEE ALSO 

hypot(3M), matherr(3M), sinh(3M). 
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NAME 

floor, ceil, fmod, fabs — floor, ceiling, remainder, absolute value 
functions 

SYNOPSIS 

#include <math.h> 

double floor (x) 
double x; 

double ceil (x) 
double x; 

double fmod (x, y) 
double x, y; 

double fabs (x) 
double x; 

DESCRIPTION 

Floor returns the largest integer (as a double-precision number) 
not greater than x. 

Ceil returns the smallest integer not less than x. 

Fmod returns the floating-point remainder of the division of x by 
y: zero if y is zero or if xfy would overflow; otherwise the number 
/ with the same sign as x, such that x = iy + / for some integer 
/, and |/| < b|. 

Fabs returns the absolute value of x, \ x\. 

SEE ALSO 

abs(3C). 
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NAME 

gamma — log gamma function 

SYNOPSIS 

#include <math.h> 

double gamma (x) 
double x; 

extern int signgam; 
DESCRIPTION 



Gamma returns ln(|r(x) |), where T(x) is defined as J e t t x 1 dt. 



The sign of T(x) is returned in the external integer signgam. The 
argument x may not be a non-positive integer. 

The following C program fragment might be used to calculate T: 

if ((y = gamma (x)) > LNMAXDOUBLE) 



y — signgam * exp(y); 

where LN MAXDOUBLE is the least value that causes exp(3M) to 
return a range error, and is defined in the <values.h> header file. 

DIAGNOSTICS 

For non-negative integer arguments HUGE is returned, and errno 
is set to EDOM. A message indicating SING error is printed on the 
standard error output. 

If the correct value would overflow, gamma returns HUGE and sets 
errno to ERANGE. 

These error-handling procedures may be changed with the function 
matherr(3M). 

SEE ALSO 

exp(3M), matherr(3M), values (5). 



o 



errorO; 
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NAME 

hypot — Euclidean distance function 

SYNOPSIS 

#include <math.h> 

double hypot (x, y) 
double x, y; 

DESCRIPTION 

Hypot returns 

sqrt(x * x + y * y), 
taking precautions against unwarranted overflows. 
DIAGNOSTICS 

When the correct value would overflow, hypot returns HUGE and 
sets errno to ERANGE. 

These error-handling procedures may be changed with the function 
matherr (3M). 

SEE ALSO 

matherr (3 M). 



UNIX Programmer's Manual 



System Calls and Library Routines— 237 



M ATHERR ( 3 M ) MATHERR (3M) 



NAME 

matherr — error-handling function 

SYNOPSIS 

#include <math.h> 

int matherr (x) 
struct exception *x; 

DESCRIPTION 

Matherr is invoked by functions in the Math Library when errors 
are detected. Users may define their own procedures for handling 
errors, by including a function named matherr in their programs. 
Matherr must be of the form described above. When an error 
occurs, a pointer to the exception structure x will be passed to the 
user-supplied matherr function. This structure, which is defined in 
the <math.h> header file, is as follows: 

struct exception { 
int type; 
char *name; 

double argl, arg2, retval; 

}; 

The element type is an integer describing the type of error that 
has occurred, from the following list of constants (defined in the 
header file) : 

DOMAIN argument domain error 
SING argument singularity 

OVERFLOW overflow range error 
UNDERFLOW underflow range error 
PLOSS partial loss of significance 

The element name points to a string containing the name of the 
function that incurred the error. The variables argl and argl are 
the arguments with which the function was invoked. Retval is set 
to the default value that will be returned by the function unless 
the user's matherr sets it to a different value. 

If the user's matherr function returns non-zero, no error message 
will be printed, and errno will not be set. If matherr is not sup- 
plied by the user, the default error-handling procedures, described 
with the math functions involved, will be invoked upon error (sum- 
marized in the table below). In every case, errno is set to EDOM 
or ERANGE and the program continues. 
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EXAMPLE 

#include <math.h> 

int 

matherr(x) 

register struct exception *x; 
{ 

switch (x— >type) { 
case DOMAIN: 

/* change sqrt to return sqrt(— argl), not 0 */ 
if (!strcmp(x— >name, "sqrt")) { 

x— >retval = sqrt(— x— >argl); 

return (0); /* print message and set errno */■ 

} 

case SING: 

/* all other domain/sing errors, print message & abort */ 
fprintf(stderr, "domain error in %s\n", x— >name); 
abort ( ); 
case PLOSS: 

/* print detailed error message */ 

fprintf(stderr, "loss of significance in %s(%g) — %g\n", 

x— >name, x— >argl, x— >retval); 
return (1); /* take no other action */ 

} 

return (0) ; /* all other errors, execute default procedure */ 
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DEFAULT ERROR HANDLING PROCEDURES 
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type 
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SING 
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SQRT: 
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GAMMA: 
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HYPOT: 






H 




SINH: 






±H 




COSH: 






H 




SIN, COS, TAN: - 








M, 0 


ASIN, ACQS, ATAN3: M 


,0 - 











ABBREVIATIONS 


* 


As much as possible of the value is returned. 


M 


Message is printed (EDOM error) . 


H 


HUGE is returned. 


-H 


—HUGE is returned. 


±H 


HUGE or -HUGE is returned. 


0 


0 is returned. 
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NAME 

sinh, cosh, tanh — hyperbolic functions 

SYNOPSIS 

#include <math.h> 

double sinh (x) 
double x; 

double cosh (x) 
double x; 

double tanh (x) 
double x; 

DESCRIPTION 

Sinh, cosh, and tanh return, respectively, the hyberbolic sine, 
cosine and tangent of their argument. 

DIAGNOSTICS 

Sinh and cosh return HUGE (and sinh may return -HUGE for 
negative x) when the correct value would overflow and set errno to 
ERANGE. 

These error-handling procedures may be changed with the function 
matherr (3M). 

SEE ALSO 

matherr (3 M). 
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NAME 

sin, cos, tan, asin, acos, atan, atan2 — trigonometric functions 



SYNOPSIS 




#include <math.h> 


double 


sin (x) 


double 


x; 


double 


cos (x) 


double 


x; 


double 


tan (x) 


double 


x; 


double 


asin (x) 


double 


x; 


double 


acos (x) 


double 


x; 


double 


atan (x) 


double 


x; 


double 


atan2 (y, x) 


double 


y» x; 


DESCRIPTION 



Sin, cos and tan return respectively the sine, cosine and tangent of 
their argument, x, measured in radians. 

Asin returns the arcsine of x, in the range —w/2 to 7r/2. 

Acos returns the arccosine of x, in the range 0 to tt. 

Atan returns the arctangent of x, in the range — tc/2 to tt/2. 

Atan2 returns the arctangent of y/x, in the range —k to ir, using 
the signs of both arguments to determine the quadrant of the 
return value. 

DIAGNOSTICS 

Sin, cos, and tan lose accuracy when their argument is far from 
zero. For arguments sufficiently large, these functions return zero 
when there would otherwise be a complete loss of significance. In 
this case a message indicating TLOSS error is printed on the stan- 
dard error output. For less extreme arguments causing partial loss 
of significance, a PLOSS error is generated but no message is 
printed. In both cases, errno is set to ERANGE. 
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If the magnitude of the argument of asin or acos is greater than 
one, or if both arguments of atan2 are zero, zero is returned and 
errno is set to EDOM. In addition, a message indicating DOMAIN 
error is printed on the standard error output. 

These error-handling procedures may be changed with the function 
matherr(3M). 

SEE ALSO 

matherr(3M). 
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NAME 

assert — verify program assertion 

SYNOPSIS 

#include <assert.h> 

assert (expression) 
int expression; 

DESCRIPTION 

This macro is useful for putting diagnostics into programs. When 
it is executed, if expression is false (zero), assert prints 

"Assertion failed: expression, file xyz, line nnn" 

on the standard error output and aborts. In the error message, 
xyz is the name of the source file and nnn the source line number 
of the assert statement. 

Compiling with the preprocessor option -DNDEBUG (see cppiX)), 
or with the preprocessor control statement "#define NDEBUG" 
ahead of the "#include <assert.h>" statement, will stop asser- 
tions from being compiled into the program. 

SEE ALSO 

abort (3C). 

cpp(l) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
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NAME 

curses — CRT screen handling and optimization package 

SYNOPSIS 

#include <curses.h> 

cc [ flags ] files — lcurses [ libraries ] 

DESCRIPTION 

These routines give the user a method of updating screens with 
reasonable optimization. In order to initialize the routines, the 
routine initscrO must be called before any of the other routines 
that deal with windows and screens are used. The routine 
endwinO should be called before exiting. To get character-at-a- 
time input without echoing, (most interactive, screen oriented- 
programs want this) after calling initscrO you should call "nonlO; 
cbreakO; noechoO;" 

The full curses interface permits manipulation of data structures 
called windows which can be thought of as two dimensional arrays 
of characters representing all or part of a CRT screen. A default 
window called stdscr is supplied, and others can be created with 
newwin. Windows are referred to by variables declared "WIN- 
DOW *", the type WINDOW is defined in curses.h to be a C struc- 
ture. These data structures are manipulated with functions 
described below, among which the most basic are move, and addch. 
(More general versions of these functions are included with names 
beginning with V, allowing you to specify a window. The rou- 
tines not beginning with *w' affect stdscr.) Then refreshO is 
called, telling the routines to make the users CRT screen look like 
stdscr. 

Mini-Curses is a subset of curses which does not allow manipula- 
tion of more than one window. To invoke this subset, use -DMINI- 
CURSES as a cc option. This level is smaller and faster than full 
curses. 

If the environment variable TERMINFO is defined, any program 
using curses will check for a local terminal definition before check- 
ing in the standard place. For example, if the standard place is 
/usr/lib/terminfo, and TERM is set to "vtlOO", then normally the 
compiled file is found in /usr/tib/terminfo/v/vtlOO. (The "v" is 
copied from the first letter of "vtlOO" to avoid creation of huge 
directories.) However, if TERMINFO is set to 
/usr /mark/my terms, curses will first check 
/opusr/mark/myterms/v/vtlOO, and if that fails, will then check 

246— System Calls and Library Routines UNIX Programmer's Manual 



CURSES (3X) 



CURSES (3X) 



/usr/lib/terminfo/v/vtlOO. This is useful for developing experi- 
mental definitions or when write permission in /usr/lib/terminfo is 
not available. 

SEE ALSO 

terminfo(4). 

FUNCTIONS 

Routines listed here may be called when using the full curses. 
Those marked with an asterisk may be called when using Mini- 
Curses. 



addch(ch)* 

addstr(str)* 

attroff(attrs)* 

attron(attrs)* 

attrset(attrs)* 

baudrateO* 

beepO* 

box (win, vert, hor) 



clear () 

clearok(win, bf) 

clrtobotO 

clrtoeolO 

cbreakO* 

delayoutput (ms) " 

delchO 

deletelnO 

delwin(win) 

doupdateO 

echoO* 

endwinO* 

erase () 

erasecharO 

fixtermO 

flashO 

flushinpO* 

getchO* 

getstr(str) 

gettmodeO 

getyx(win, y, x) 



add a character to stdscr (like putchar) 

(wraps to next line at end of line) 

calls addch with each character in str 

turn off attributes named 

turn on attributes named 

set current attributes to attrs 

current terminal speed 

sound beep on terminal 

draw a box around edges of win 

vert and hor are chars to use for vert, and 

hor. edges of box 

clear stdscr 

clear screen before next redraw of win 
clear to bottom of stdscr 
clear to end of line on stdscr 
set cbreak mode 

insert ms millisecond pause in output 
delete a character 
delete a line 
delete win 

update screen from all wnooutrefresh 
set echo mode 
end window modes 
erase stdscr 

return user's erase character 
restore tty to "in curses" state 
flash screen or beep 
throw away any typeahead 
get a char from tty 
get a string through stdscr 
establish current tty modes 
get (y, x) co-ordinates 
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has_ic() true if terminal can do insert character 

has ilO true if terminal can do insert line 

idlok(win, bf)* use terminal's insert/delete line if bf !-= 0 

inchO get char at current (y, x) co-ordinates 

initscr ( ) * initialize screens 

insch(c) insert a char 

insertlnO insert a line 

intrflush(win, bf) interrupts flush output if bf is TRUE 

keypad (win, bf) enable keypad input 

killcharO return current user's kill character 

leaveok(win, flag) OK to leave cursor anywhere after refresh if 

flag!— 0 for win, otherwise cursor must be left 
at current position, 
return verbose name of terminal 
allow meta characters on input if flag !— 0 
move to (y, x) on stdscr 
move(y, x) then addch(ch) 
similar... 

newrow, newcoOlow level cursor motion 
like delch, but move(y, x) first 
etc. 



longnameO 
meta (win, flag)* 
move(y, x)* 
mvaddch(y, x, ch) 
mvaddstr(y, x, str) 
mvcur(oldrow, oldcol. 
mvdelch(y, x) 
mvgetch(y, x) 
mvgetstr(y, x) 
mvinch(y, x) 
mvinsch(y, x, c) 
mvprintw(y, x, fmt, args) 
mvscanw(y, x, fmt, args) 
mvwaddch(win, y, x, ch) 
mvwaddstr(win, y, x, str) 
mvwdelch(win, y, x) 
mvwgetch(win, y, x) 
mvwgetstr(win, y, x) 
mvwin(win, by, bx) 
mvwinch(win, y, x) 
mvwinsch(win, y, x, c) 
mvwprintw(win, y, x, fmt, args) 
mvwscanw(win, y, x, fmt, args) 

newpad(nlines, ncols) create a new pad with given dimensions 

newterm(type, fd) set up new terminal of given type to output on fd 

newwin (lines, cols, begin_y, begin_x) create a new window 

nl ( ) * set newline mapping 

nocbreak ( ) * unset cbreak mode 

nodelay(win, bf) enable nodelay input mode through getch 
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noechoO* 

nonlO* 

norawO* 

overlay (win 1, win2) 
overwrite (win 1, win2) 



unset echo mode 
unset newline mapping 
unset raw mode 
overlay winl on win2 
overwrite winl on top of win2 



pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

like prefresh but with no output until doupdate called 
prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

refresh from pad starting with given upper left corner 
with output to given portion of screen 
printf on stdscr 
set raw mode 

make current screen look like stdscr 
set tty modes to "out of curses" state 
reset tty flags to stored value 
save current modes as "in curses" state 
store current tty flags 
scanf through stdscr 
scroll win one line 
allow terminal to scroll if flag !«= 0 
now talk to terminal new 
set user scrolling region to lines t through b 
establish terminal with given type 



printw(fmt, argl, arg2, ...) 

rawO* 

refreshO* 

resettermO* 

resettyO* 

savetermO* 

savettyO* 

scanw(fmt, argl, arg2, ...) 
scroll (win) 
scrollok(win, flag) 
set_term(new) 
setscrreg(t, b) 
setterm(type) 



setupterm(term, filenum, errret) 

standend ( ) * clear standout mode attribute 

standoutO* set standout mode attribute 

subwin(win, lines, cols, begin_y, begin_x) create a subwindow 



touch win (win) 

traceoffO 

traceonO 

typeahead(fd) 

unctrl(ch)* 

waddch(win, ch) 

waddstr(win, str) 

wattroff(win, attrs) 

wattron(win, attrs) 

wattrset(win, attrs) 

wclear(win) 

wclrtobot(win) 

wclrtoeol(win) 

wdelch(win, c) 

wdeleteln(win) 



change all of win 

turn off debugging trace output 

turn on debugging trace output 

use file descriptor fd to check typeahead 

printable version of ch 

add char to win 

add string to win 

turn off attrs in win 

turn on attrs in win 

set attrs in win to attrs 

clear win 

clear to bottom of win 
clear to end of line on win 
delete char from win 
delete line from win 
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werase(win) erase win 

wgetch(win) get a char through win 

wgetstr(win, str) get a string through win 

winch (win) get char at current (y, x) in win 

winsch(win, c) insert char into win 

winsertln(win) insert line into win 

wmove(win, y, x) set current (y, x) co-ordinates on win 

wnoutrefresh(win) refresh but no screen output 
wprintw(win, fmt, argl, arg2, ...) printf on win 

wrefresh(win) make screen look like win 
wscanw(win, fmt, argl, arg2, ...) scanf through win 

wsetscrreg(win, t, b) set scrolling region of win 

wstandend(win) clear standout attribute in win 

wstandout(win) set standout attribute in win 



TERMINFO LEVEL ROUTINES 

These routines should be called by programs wishing to deal 
directly with the terminfo database. Due to the low level of this 
interface, it is discouraged. Initially, setupterm should be called. 
This will define the set of terminal dependent variables defined in 
terminfo(4). The include files <curses.h> and <term.h> should 
be included to get the definitions for these strings, numbers, and 
flags. Parmeterized strings should be passed through tparm to 
instantiate them. All terminfo strings (including the output of 
tparm) should be printed with tputs or putp . Before exiting, 
resetterm should be called to restore the tty modes. (Programs 
desiring shell escapes or suspending with control Z can call reset - 
term before the shell is called and fixterm after returning from the 
shell.) 

fixterm 0 restore tty modes for terminfo use 



250— System Calls and Library Routines UNIX Programmer's Manual 



resetterm () 

setupterm (term, fd, rc) 



tparm(str, pi, p2, p9) 
tputs (str, affcnt, putc) 



putp (str) 



(called by setupterm) 

reset tty modes to state before program entry 

read in database. Terminal type is the 

character string term, all output is to UNIX System file 

descriptor fd. A status value is returned in the 

integer pointed to by rc: 1 is normal. The simplest 

call would be setupterm(0, 1, 0) which uses all the defaults. 

instantiate string str with parms p- 

apply padding info to string str. 

affcnt is the number of lines affected, or 1 if 

not applicable. Putc is a putchar-like function 

to which the characters are passed, one at a time. 

handy function that calls tputs (str, 1, putchar). 
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vidputs(attrs, putc) 



vidattr(attrs) 



output the string to put terminal in video attribute 
mode attrs, which is any combination of the attributes 
listed below. Chars are passed to putchar-like function putc. 
Like vidputs but outputs through putchar 



TERMCAP COMPATIBILITY ROUTINES 

These routines were included as a conversion aid for programs that 
use termcap. Their parameters are the same as for termcap. 
They are emulated using the terminfo database. They may go 
away at a later date. 

look up termcap entry for name 
get boolean entry for id 
get numeric entry for id 
get string entry for id 
apply parms to given cap 
apply padding to cap calling fn as putchar 



tgetent(bp, name) 
tgetflag(id) 
tgetnum(id) 
tgetstrCid, area) 
tgoto(cap, col, row) 
tputs(cap, affcnt, fn) 



ATTRIBUTES 

The following video 
attron ,attroff,attrset . 



attributes can be passed to the functions 



A 


STANDOUT 


Terminal's best highlighting mode 


A 


UNDERLINE 


Underlining 


A 


REVERSE 


Reverse video 


A 


BLINK 


Blinking 


A 


DIM 


Half bright 


A 


BOLD 


Extra bright or bold 


A 


BLANK 


Blanking (invisible) 


A 


PROTECT 


Protected 


A 


ALTCHARSET 


Alternate character set 



FUNCTION KEYS 

The following function keys might be returned by getch if keypad 
has been enabled. Note that not all of these are currently sup- 
ported, due to lack of definitions in terminfo or the terminal not 
transmitting a unique code when the key is pressed. 

Key name 

break key (unreliable) 
The four arrow keys ... 



Home key (upward+left arrow) 

backspace (unreliable) 

Function keys. Space for 64 is reserved. 



Name 


Value 


KEYBREAK 


0401 


KEYDOWN 


0402 


KEY_UP 


0403 


KEYLEFT 


0404 


KEYRIGHT 


0405 


KEYHOME 


0406 


KEYBACKSPACE 


0407 


KEYFO 


0410 
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KEY F(n) 


(KEYJF0+(n)) Formula for fn. 


KEY DL 


0510 


Delete line 


KEYIL 


0511 


Insert line 


KEYDC 


0512 


Delete character 


KEYJC 


0513 


Insert char or enter insert mode 


KEYEIC 


0514 


Exit insert char mode 


KEY CLEAR 


0515 


Clear screen 


KEY EOS 


0516 


Clear to end of screen 


KEY EOL 


0517 


Clear to end of line 


KEY SF 


0520 


Scroll 1 line forward 


KEY SR 


0521 


Scroll 1 line backwards (reverse) 


KEYNPAGE 


0522 


Next page 


KEYPPAGE 


0523 


Previous page 


KEYSTAB 


0524 


Set tab 


KEYCTAB 


0525 


Clear tab 


KEYCATAB 


0526 


Clear all tabs 


KEYENTER 


0527 


Enter or send (unreliable) 


KEYSRESET 


0530 


soft (partial) reset (unreliable) 


KEYRESET 


0531 


reset or hard reset (unreliable) 


KEYPRINT 


0532 


print or copy 


KEY_LL 


0533 


home down or bottom (lower left) 


WARNING 







The plotting library plot OX) and the curses library curses (3X) 
both use the names erase 0 and move(). The curses versions are 
macros. If you need both libraries, put the plot(3X) code in a 
different source file than the curses (3X) code, and/or #undef 
moveO and erase () in the plot(3X) code. 
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NAME 

ldahread — read the archive header of a member of an archive file 

SYNOPSIS 

#include <stdio.h> 
#include <ar.h> 
#include <filehdr.h> 
#include <ldfcn.h> 

int ldahread (Idptr, arhead) 
LDFILE *ldptr; 
ARCHDR *arhead; 

DESCRIPTION 

If TYPEildptr) is the archive file magic number, ldahread reads 
the archive header of the common object file currently associated 
with Idptr into the area of memory beginning at arhead. 

Ldahread returns SUCCESS or FAILURE. Ldahread will fail if 
TYPE(ldptr) does not represent an archive file, or if it cannot read 
the archive header. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4), ar(4). 
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NAME 

ldclose, ldaclose — close a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldclose (ldptr) 
LDFILE *ldptr; 

int ldaclose (ldptr) 
LDFILE *ldptr; 

DESCRIPTION 

Ldopen (3X) and ldclose are designed to provide uniform access to 
both simple object files and object files that are members of 
archive files. Thus an archive of common object files can be pro- 
cessed as if it were a series of simple common object files. 

If TYPE(ldptr) does not represent an archive file, ldclose will close 
the file and free the memory allocated to the LDFILE structure 
associated with ldptr. If TYPE(ldptr) is the magic number of an 
archive file, and if there are any more files in the archive, ldclose 
will reinitialize OFFSET(Wpfr) to the file address of the next 
archive member and return FAILURE. The LDFILE structure is 
prepared for a subsequent IdopenOX) . In all other cases, ldclose 
returns SUCCESS. 

Ldaclose closes the file and frees the memory allocated to the 
LDFILE structure associated with ldptr regardless of the value of 
TYPE(ldptr). Ldaclose always returns SUCCESS. The function is 
often used in conjunction with Idaopen. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

fclose(3S) , IdopenOX) , ldfcn (4) . 
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NAME 

ldfhread — read the file header of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldfhread (ldptr, filehead) 
LDFILE *ldptr; 
FILHDR «filehead; 

DESCRIPTION 

Ldfhread reads the file header of the common object file currently 
associated with ldptr into the area of memory beginning at 
filehead. 

Ldfhread returns SUCCESS or FAILURE. Ldfhread will fail if it 
cannot read the file header. 

In most cases the use of ldfhread can be avoided by using the 
macro HEADER (ldptr) defined in ldfcn.h (see ldfcn (4)). The 
information in any field, fieldname, of the file header may be 
accessed using HEADER (ldptr) .fieldname. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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NAME 

ldgetname — retrieve symbol name for common object file symbol 
table entry 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <syms.h> 
#include <ldfcn.h> 

char * ldgetname (ldptr, symbol) 
LDFILE *ldptr; 
SYMENT *symbol; 

DESCRIPTION 

Ldgetname returns a pointer to the name associated with symbol 
as a string. The string is contained in a static buffer local to 
ldgetname that is overwritten by each call to ldgetname, and 
therefore must be copied by the caller if the name is to be saved. 

As of UNIX System V Release 2.0, the common object file format 
has been extended to handle arbitrary length symbol names with 
the addition of a "string table". Ldgetname will return the symbol 
name associated with a symbol table entry for either a pre-UNIX 
System V Release 2.0 object file or a UNIX System V Release 2.0 
object file. Thus, ldgetname can be used to retrieve names from 
object files without any backward compatibility problems. Ldget- 
name will return NULL (defined in stdio.h) for an object file if the 
name cannot be retrieved. This situation can occur: 

— if the "string table" cannot be found, 

— if not enough memory can be allocated for the string 
table, 

— if the string table appears not to be a string table (for 
example, if an auxiliary entry is handed to ldgetname that 
looks like a reference to a name in a non-existent string 
table), or 

— if the name's offset into the string table is past the end of 
the string table. 

Typically, ldgetname will be called immediately after a successful 
call to Idtbread to retrieve the name associated with the symbol 
table entry filled by Idtbread. 
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The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 
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NAME 

ldlread, ldlinit, ldlitem — manipulate line number entries of a com- 
mon object file function 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <linenum.h> 

#include <ldfcn.h> 



int ldlread (ldptr, fcnindx, linenum, linent) 
LDFILE *ldptr; 
long fcnindx; 
unsigned short linenum; 
LINENO linent; 

int ldlinit (ldptr, fcnindx) 
LDFILE *ldptr; 
long fcnindx; 

int ldlitem (ldptr, linenum, linent) 
LDFILE *ldptr; 
unsigned short linenum; 
LINENO linent; 

DESCRIPTION 

Ldlread searches the line number entries of the common object file 
currently associated with ldptr. Ldlread begins its search with the 
line number entry for the beginning of a function and confines its 
search to the line numbers associated with a single function. The 
function is identified by fcnindx, the index of its entry in the 
object file symbol table. Ldlread reads the entry with the smallest 
line number equal to or greater than linenum into linent . 

Ldlinit and ldlitem together perform exactly the same function as 
ldlread. After an initial call to ldlread or ldlinit, ldlitem may be 
used to retrieve a series of line number entries associated with a 
single function. Ldlinit simply locates the line number entries for 
the function identified by fcnindx. Ldlitem finds and reads the 
entry with the smallest line number equal to or greater than line- 
num into linent. 

Ldlread, ldlinit, and ldlitem each return either SUCCESS or 
FAILURE. Ldlread will fail if there are no line number entries in 
the object file, if fcnindx does not index a function entry in the 
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symbol table, or if it finds no line number equal to or greater than 
linenum. Ldlinit will fail if there are no line number entries in the 
object file or if fcnindx does not index a function entry in the sym- 
bol table. Ldlitem will fail if it finds no line number equal to or 
greater than linenum. 

The programs must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbindex(3X), ldfcn(4). 
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NAME 

ldlseek, ldnlseek — seek to line number entries of a section of a 
common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldlseek (ldptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int ldnlseek (ldptr, sectname) 
LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

Ldlseek seeks to the line number entries of the section specified by 
sectindx of the common object file currently associated with ldptr. 

Ldnlseek seeks to the line number entries of the section specified 
by sectname. 

Ldlseek and ldnlseek return SUCCESS or FAILURE. Ldlseek will 
fail if sectindx is greater than the number of sections in the object 
file; ldnlseek will fail if there is no section name corresponding 
with *sectname. Either function will fail if the specified section 
has no line number entries or if it cannot seek to the specified line 
number entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

ldohseek — seek to the optional file header of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldohseek (ldptr) 
LDFILE *Idptr; 

DESCRIPTION 

Ldohseek seeks to the optional file header of the common object 
file currently associated with ldptr. 

Ldohseek returns SUCCESS or FAILURE. Ldohseek will fail if the 
object file has no optional header or if it cannot seek to the 
optional header. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfhread(3X), ldfcn(4). 
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NAME 

ldopen, ldaopen — open a common object file for reading 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

LDFILE * ldopen (filename, ldptr) 
char 'filename; 
LDFILE 'ldptr; 

LDFILE *ldaopen (filename, oldptr) 
char 'filename; 
LDFILE *oldptr; 

DESCRIPTION 

Ldopen and ldclose(3X) are designed to provide uniform access 
to both simple object files and object files that are members of 
archive files. Thus an archive of common object files can be pro- 
cessed as if it were a series of simple common object files. 

If ldptr has the value NULL, then ldopen will open filename and 
allocate and initialize the LDFILE structure, and return a pointer 
to the structure to the calling program. 

If ldptr is valid and if TYPE(ldptr) is the archive magic number, 
ldopen will reinitialize the LDFILE structure for the next archive 
member of filename. 

Ldopen and ldclose (3X) are designed to work in concert. Ldclose 
will return FAILURE only when TYPE(ldptr) is the archive magic 
number and there is another file in the archive to be processed. 
Only then should ldopen be called with the current value of ldptr. 
In all other cases, in particular whenever a new filename is opened, 
ldopen should be called with a NULL ldptr argument. 

The following is a prototype for the use of ldopen and 
ldclose (3X). 
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/* for each filename to be processed */ 

ldptr - NULL; 

do 

{ 

if ( (ldptr - ldopen (filename, ldptr)) != NULL ) 
{ 

/* check magic number */ 
/* process the file */ 

} 

} while (ldclose (ldptr) ~ FAILURE ); 

If the value of oldptr is not NULL, Idaopen will open filename 
anew and allocate and initialize a new LDFILE structure, copying 
the TYPE, OFFSET, and HEADER fields from oldptr. Ldaopen 
returns a pointer to the new LDFILE structure. This new pointer is 
independent of the old pointer, oldptr. The two pointers may be 
used concurrently to read separate parts of the object file. For 
example, one pointer may be used to step sequentially through the 
relocation information, while the other is used to read indexed 
symbol table entries. 

Both ldopen and Idaopen open filename for reading. Both func- 
tions return NULL if filename cannot be opened, or if memory for 
the LDFILE structure cannot be allocated. A successful open does 
not insure that the given file is a common object file or an archived 
object file. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

fopen (3S) , ldclose (3X) , ldfcn (4) . 
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NAME 

ldrseek, ldnrseek — seek to relocation entries of a section of a com- 
mon object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldrseek (ldptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int ldnrseek (ldptr, sectname) 
LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

Ldrseek seeks to the relocation entries of the section specified by 
sectindx of the common object file currently associated with ldptr. 

Ldnrseek seeks to the relocation entries of the section specified by 
sectname. 

Ldrseek and ldnrseek return SUCCESS or FAILURE. Ldrseek will 
fail if sectindx is greater than the number of sections in the object 
file; ldnrseek will fail if there is no section name corresponding 
with sectname. Either function will fail if the specified section has 
no relocation entries or if it cannot seek to the specified relocation 
entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), IdopenOX), IdshreadOX), ldfcn(4). 



264— System Calls and Library Routines 



UNIX Programmer's Manual 



LDSHREAD (3X) 



LDSHREAD (3X) 



NAME 

ldshread, ldnshread — read an indexed/named section header of a 
common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <scnhdr.h> 

#include <ldfcn.h> 

int ldshread (ldptr, sectindx, secthead) 
LDFILE *ldptr; 
unsigned short sectindx; 
SCNHDR *secthead; 

int ldnshread (ldptr, sectname, secthead) 
LDFILE *ldptr; 
char *sectname; 
SCNHDR *secthead; 

DESCRIPTION 

Ldshread reads the section header specified by sectindx of the 
common object file currently associated with ldptr into the area of 
memory beginning at secthead. 

Ldnshread reads the section header specified by sectname into the 
area of memory beginning at secthead. 

Ldshread and ldnshread return SUCCESS or FAILURE. Ldshread 
will fail if sectindx is greater than the number of sections in the 
object file; ldnshread will fail if there is no section name 
corresponding with sectname. Either function will fail if it cannot 
read the specified section header. 

Note that the first section header has an index of one. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldcloseOX), ldopen(3X), ldfcn(4). 
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NAME 

ldsseek, ldnsseek — seek to an indexed/named section of a common 
object file 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <ldfcn.h> 

int ldsseek (ldptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int ldnsseek (ldptr, sectname) 
LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

Ldsseek seeks to the section specified by sectindx of the common 
object file currently associated with ldptr. 

Ldnsseek seeks to the section specified by sectname. 

Ldsseek and ldnsseek return SUCCESS or FAILURE. Ldsseek will 
fail if sectindx is greater than the number of sections in the object 
file; ldnsseek will fail if there is no section name corresponding 
with sectname. Either function will fail if there is no section data 
for the specified section or if it cannot seek to the specified section. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

ldtbindex — compute the index of a symbol table entry of a com- 
mon object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

long ldtbindex (ldptr) 
LDFILE «ldptr; 

DESCRIPTION 

Ldtbindex returns the (long) index of the symbol table entry at the 
current position of the common object file associated with ldptr. 

The index returned by ldtbindex may be used in subsequent calls 
to ldtbread(3X). However, since ldtbindex returns the index of 
the symbol table entry that begins at the current position of the 
object file, if ldtbindex is called immediately after a particular 
symbol table entry has been read, it will return the index of the 
next entry. 

Ldtbindex will fail if there are no symbols in the object file, or if 
the object file is not positioned at the beginning of a symbol table 
entry. 

Note that the first symbol in the symbol table has an index of 
zero. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldcloseOX), ldopen(3X), ldtbreadOX), ldtbseek(3X), ldfcn(4). 
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NAME 

ldtbread — read an indexed symbol table entry of a common object 
file 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <syms.h> 
#include <ldfcn.h> 

int ldtbread (ldptr, symindex, symbol) 
LDFILE *ldptr; 
long symindex; 
SYMENT ♦symbol; 

DESCRIPTION 

Ldtbread reads the symbol table entry specified by symindex of the 
common object file currently associated with ldptr into the area of 
memory beginning at symbol. 

Ldtbread returns SUCCESS or FAILURE. Ldtbread will fail if 
symindex is greater than the number of symbols in the object file, 
or if it cannot read the specified symbol table entry. 

Note that the first symbol in the symbol table has an index of 
zero. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbseek(3X), ldgetname(3X), ldfcn(4). 
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NAME 

ldtbseek — seek to the symbol table of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldtbseek (ldptr) 
LDFILE *ldptr; 

DESCRIPTION 

Ldtbseek seeks to the symbol table of the object file currently 
associated with ldptr. 

Ldtbseek returns SUCCESS or FAILURE. Ldtbseek will fail if the 
symbol table has been stripped from the object file, or if it cannot 
seek to the symbol table. 

The program must be loaded with the object file access routine 
library libld.a. 

SEE ALSO 

ldcloseOX), ldopen(3X), ldtbread(3X), ldfcn(4). 
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NAME 

logname — return login name of user 

SYNOPSIS 

char * logname ( ) 

DESCRIPTION 

Logname returns a pointer to the null-terminated login name; it 
extracts the SLOGNAME variable from the user's environment. 

This routine is kept in /lib/libPW.a. 

FILES 

/etc/profile 

SEE ALSO 

profile (4), environ (5). 

env(l), login(l) in the UNIX Programmer's Manual— Volume 1: 
Commands and Utilities. 

BUGS 

The return values point to static data whose content is overwritten 
by each call. 

This method of determining a login name is subject to forgery. 
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NAME 

malloc, free, realloc, calloc, mallopt, mallinfo — fast main memory 
allocator 

SYNOPSIS 

#include <malloc.h> 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realloc (ptr, size) 
char *ptr; 
unsigned size; 

char ♦calloc (nelem, elsize) 
unsigned nelem, elsize; 

int mallopt (cmd, value) 
int cmd, value; 

struct mallinfo mallinfo (max) 
int max; 

DESCRIPTION 

Malloc and free provide a simple general-purpose memory alloca- 
tion package, which runs considerably faster than the malloc (30 
package. It is found in the library "malloc", and is loaded if the 
option "— lmalloc" is used with cc(\) or Id (I). 

Malloc returns a pointer to a block of at least size bytes suitably 
aligned for any use. 

The argument to free is a pointer to a block previously allocated 
by malloc; after free is performed this space is made available for 
further allocation, and its contents have been destroyed (but see 
mallopt below for a way to change this behavior). 

Undefined results will occur if the space assigned by malloc is 
overrun or if some random number is handed to free. 

Realloc changes the size of the block pointed to by ptr to size 
bytes and returns a pointer to the (possibly moved) block. The 
contents will be unchanged up to the lesser of the new and old 

sizes. 

Calloc allocates space for an array of nelem elements of size 
elsize. The space is initialized to zeros. 
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Mallopt provides for control over the allocation algorithm, 
available values for cmd are: 



The 



M MXFAST Set maxfast to value. The algorithm allocates all 
blocks below the size of maxfast in large groups 
and then doles them out very quickly. The default 
value for maxfast is 0. 

M NLBLKS Set numlblks to value. The above mentioned 
"large groups" each contain numlblks blocks. 
Numlblks must be greater than 0. The default 
value for numlblks is 100. 

M GRAIN Set grain to value. The sizes of all blocks smaller 
than maxfast are considered to be rounded up to 
the nearest multiple of grain. Grain must be 
greater than 0. The default value of grain is the 
smallest number of bytes which will allow align- 
ment of any data type. Value will be rounded up to 
a multiple of the default when grain is set. 

M KEEP Preserve data in a freed block until the next mal- 
loc, realloc, or calloc. This option is provided only 
for compatibility with the old version of malloc and 
is not recommended. 

These values are defined in the <malloc.h> header file. 

Mallopt may be called repeatedly, but may not be called after the 
first small block is allocated. 

Mallinfo provides instrumentation describing space usage. It 
returns the structure: 

struct mallinfo { 

total space in arena */ 
number of ordinary blocks */ 
number of small blocks */ 
space in holding block headers */ 
number of holding blocks */ 
/* space in small blocks in use */ 
space in free small blocks */ 
space in ordinary blocks in use */ 
space in free ordinary blocks */ 
space penalty if keep option */ 
is used */ 



int arena; 


/* 


int ordblks; 


/* 


int smblks; 


/* 


int hblkhd; 


/* 


int hblks; 


/* 


int usmblks; 


/* 


int fsmblks; 


/* 


int uordblks; 


/* 


int fordblks; 


/* 


int keepcost; 


/* 




/* 
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This structure is defined in the < malloc.h > header file. 

Each of the allocation routines returns a pointer to space suitably 
aligned (after possible pointer coercion) for storage of any type of 
object. 

SEE ALSO 

brk(2), mallocOC). 

DIAGNOSTICS 

Malloc, realloc and calloc return a NULL pointer if there is not 
enough available memory. When realloc returns NULL, the block 
pointed to by ptr is left intact. If mallopt is called after any allo- 
cation or if cmd or value are invalid, non-zero is returned. Other- 
wise, it returns zero. 

WARNINGS 

This package usually uses more data space than malloc (3C). 
The code size is also bigger than malloc (30 . 
Note that unlike malloc (30, this package does not preserve the 
contents of a block when it is freed, unless the M KEEP option of 
mallopt is used. 

Undocumented features of malloc (30 have not been duplicated. 
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NAME 

plot — graphics interface subroutines 

SYNOPSIS 

openpl () 

erase 0 

label (s) 
char *s; 

line (xl, yl, x2, y2) 
int xl, yl, x2, y2; 

circle (x, y, r) 
int x, y, r; 

arc (x, y, xO, yO, xl, yl) 
int x, y, xO, yO, xl, yl; 

move (x, y) 
int x, y; 

cont (x, y) 
int x, y; 

point (x, y) 
int x, y; 

linemod (s) 
char *s; 

space (xO, yO, xl, yl) 
int xO, yO, xl, yl; 

closepl 0 

DESCRIPTION 

These subroutines generate graphic output in a relatively device- 
independent manner. Space must be used before any of these 
functions to declare the amount of space necessary. See plot (4). 
Openpl must be used before any of the others to open the device 
for writing. Closepl flushes the output. 

Circle draws a circle of radius r with center at the point (x, y). 

Arc draws an arc of a circle with center at the point (x, y) 
between the points (xO, yO) and (xl, yl). 

String arguments to label and linemod are terminated by nulls 
and do not contain new-lines. 
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FILES 



See plot (4) for a description of the effect of the remaining func- 
tions. 

The library files listed below provide several flavors of these rou- 
tines. 

/usr/lib/libplot.a produces output for tplotiXG) filters 

/usr/lib/lib300.a for DASI 300 

/usr/lib/lib300s.a for DASI 300s 

/usr/lib/lib450.a for DASI 450 

/usr/lib/lib40 1 4.a for TEKTRONIX 40 1 4 

WARNINGS 

In order to compile a program containing these functions in file.c 
it is necessary to use "cc file.c — lplot". 

In order to execute it, it is necessary to use "a.out | tplot". 

The above routines use <stdio.h>, which causes them to increase 
the size of programs, not otherwise using standard I/O, more than 
might be expected. 

SEE ALSO 

plot (4). 

graph(lG), stat(lG), tplot(lG) in the UNIX Programmer's 
Manual —Volume 1: Commands and Utilities. 
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NAME 

regcmp, regex — compile and execute regular expression 
SYNOPSIS 

char *regcmp (stringl I, string2, ...1, (char *)0) 
char *stringl, *string2, 

char *regex (re, subject!, retO, ...J) 
char *re, ^subject, *retO, 

extern char * loci; 

DESCRIPTION 

Regcmp compiles a regular expression and returns a pointer to the 
compiled form. Malloc (3C) is used to create space for the vector. 
It is the user's responsibility to free unneeded space so allocated. 
A NULL return from regcmp indicates an incorrect argument. 
Regcmp (I) has been written to generally preclude the need for 
this routine at execution time. 

Regex executes a compiled pattern against the subject string. 
Additional arguments are passed to receive values back. Regex 
returns NULL on failure or a pointer to the next unmatched char- 
acter on success. A global character pointer loci points to 

where the match began. Regcmp and regex were mostly borrowed 
from the editor, ed{\)\ however, the syntax and semantics have 
been changed slightly. The following are the valid symbols and 
their associated meanings. 

1 1 * . A These symbols retain their current meaning. 

$ Matches the end of the string; \n matches a new-line. 

— Within brackets the minus means through. For example, 

la— zl is equivalent to [abed. ..xyzl. The — can appear 
as itself only if used as the first or last character. For 
example, the character class expression 11 — 1 matches the 
characters 1 and — . 

+ A regular expression followed by + means one or more 

times. For example, 10—91+ is equivalent to 
10-9110-91*. 

{m} {m,} {m,u} 

Integer values enclosed in {} indicate the number of 
times the preceding regular expression is to be applied. 
The value m is the minimum number and u is a number, 
less than 256, which is the maximum. If only m is 
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present (e.g., {m}), it indicates the exact number of times 
the regular expression is to be applied. The value {m,} is 
analogous to {m,infinity}. The plus (+) and star (*) 
operations are equivalent to {l,} and {0,} respectively. 

(...)$« The value of the enclosed regular expression is to be 
returned. The value will be stored in the (n+l)th argu- 
ment following the subject argument. At most ten 
enclosed regular expressions are allowed. Regex makes 
its assignments unconditionally. 

(...) Parentheses are used for grouping. An operator, e.g., *, 
+, {}, can work on a single character or a regular 
expression enclosed in parentheses. For example, 
(a*(cb+)*)$0. 

By necessity, all the above defined symbols are special. They 
must, therefore, be escaped to be used as themselves. 

EXAMPLES 

Example 1: 

char *cursor, *newcursor, *ptr; 

newcursor — regex((ptr — regcmp(" A \n", 0)), cursor); 
free(ptr); 

This example will match a leading new-line in the subject string 
pointed at by cursor. 

Example 2: 

char ret0[9]; 

char *newcursor, *name; 

name - regcmp("([A-Za-z][A-za-zO-9j{0,7})$0", 0); 
newcursor — regex(name, M 123Testing321", retO); 

This example will match through the string "Testing3" and will 
return the address of the character after the last matched charac- 
ter (cursor+11). The string "Testing3" will be copied to the char- 
acter array retO. 

Example 3: 

#include "file.i" 

char *string, *newcursor; 

newcursor = regex (name, string); 
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This example applies a precompiled regular expression in file.i (see 
regcmpiX)) against string. 

This routine is kept in /Iib/IibPW.a. 

SEE ALSO 

mallocOC). 

ed(l), regcmp(l) in the UNIX Programmer's Manual— Volume 1: 
Commands and Utilities. 

BUGS 

The user program may run out of memory if regcmp is called 
iteratively without freeing the vectors no longer required. The fol- 
lowing user-supplied replacement for mallocOC) reuses the same 
vector saving time and space: 

/* user's program */ 

char * 
malloc(n) 
unsigned n; 
{ 

static char rebuf[512]; 

return (n <— sizeof rebuf) ? rebuf : NULL; 

} 
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NAME 

sputl, sgetl — access long integer data in a machine-independent 
fashion. 

SYNOPSIS 

void sputl (value, buffer) 
long value; 
char *buffer; 

long sgetl (buffer) 
char *buffer; 

DESCRIPTION 

Sputl takes the four bytes of the long integer value and places 
them in memory starting at the address pointed to by buffer. The 
ordering of the bytes is the same across all machines. 

Sgetl retrieves the four bytes in memory starting at the address 
pointed to by buffer and returns the long integer value in the byte 
ordering of the host machine. 

The combination of sputl and sgetl provides a machine- 
independent way of storing long numeric data in a file in binary 
form without conversion to characters. 

A program which uses these functions must be loaded with the 
object-file access routine library libld.a. 
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NAME 

vprintf, vfprintf, vsprintf — print formatted output of a varargs 
argument list 

SYNOPSIS 

#include <stdio.h> 
#include <varargs.h> 

int vprintf (format, ap) 
char *format; 
va_list ap; 

int vfprintf (stream, format, ap) 
FILE *stream; 
char *format; 
valist ap; 

int vsprintf (s, format, ap) 
char *s, ♦format; 
va list ap; 

DESCRIPTION 

vprintf, vfprintf, and vsprintf are the same as printf, fprintf, and 
sprintf respectively, except that instead of being called with a vari- 
able number of arguments, they are called with an argument list 
as defined by varargs (5) . 

EXAMPLE 

The following demonstrates how vfprintf could be used to write an 
error routine. 

#include <stdio.h> 
#include <varargs.h> 



/• 

* error should be called like 

* error (function name, format, argl, arg2...); 
*/ 

/*VARARGS0*/ 
void 

error (vaalist) 

/* Note the function name and format arguments cannot be 

* separately declared because of the definition of varargs. 
*/ 
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vadcl 
{ 

va list args; 
char *fmt; 

vastart(args); 

/* print out name of function causing error */ 

(void)fprintf(stderr, "ERROR in %s: H , va_arg(args, char *)); 

fmt — va_arg(args, char *); 

/» print out remainder of message */ 

(void) vfprintf (fmt, args); 

vaend(args); 

(void) abort ( ); 

} 

SEE ALSO 

printf(3S), varargs(5). 
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NAME 

abort — terminate Fortran program 

SYNOPSIS 

call abort ( ) 

DESCRIPTION 

Abort terminates the program which calls it, closing all open files 
truncated to the current position of the file pointer. The abort 
usually results in a core dump. 

DIAGNOSTICS 

When invoked, abort prints "Fortran abort routine called" on the 
standard error output. The message "abort - core dumped" is sent 
to the terminal. 

SEE ALSO 

abort (3 C). 
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NAME 

abs, iabs, dabs, cabs, zabs — Fortran absolute value 

SYNOPSIS 

integer il, 12 
real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 
double complex dxl, dx2 

r2 = abs(rl) 

i2 = iabs(il) 
i2 - abs(il) 

dp2 = dabs (dpi) 
dp2 = abs (dpi) 

cx2 = cabs(cxl) 
cx2 = abs (cxl) 

dx2 = zabs(dxl) 
dx2 - abs(dxl) 

DESCRIPTION 

Abs is the family of absolute value functions. labs returns the 
integer absolute value of its integer argument. Dabs returns the 
double-precision absolute value of its double-precision argument. 
Cabs returns the complex absolute value of its complex argument. 
Zabs returns the double-complex absolute value of its double- 
complex argument. The generic form abs returns the type of its 
argument. 

SEE ALSO 

floor (3M). 
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NAME 

acos, dacos — Fortran arccosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = acos(rl) 

dp2 = dacos (dpi) 
dp2 = acos (dpi) 

DESCRIPTION 

Acos returns the real arccosine of its real argument. Dacos 
returns the double-precision arccosine of its double-precision argu- 
ment. The generic form acos may be used with impunity as its 
argument will determine the type of the returned value. 

SEE ALSO 

trig(3M). 
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NAME 

aimag, dimag — Fortran imaginary part of complex argument 

SYNOPSIS 

real r 

complex cxr 
double precision dp 
double complex cxd 

r — aimag (cxr) 

dp = dimag(cxd) 

DESCRIPTION 

Aimag returns the imaginary part of its single-precision complex 
argument. Dimag returns the double-precision imaginary part of 
its double-complex argument. 
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NAME 

aint, dint — Fortran integer part intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = aint(rl) 

dp2 = dint(dpl) 
dp2 = aint (dpi) 

DESCRIPTION 

Aint returns the truncated value of its real argument in a real. 
Dint returns the truncated value of its double-precision argument 
as a double-precision value. Aint may be used as a generic func- 
tion name, returning either a real or double-precision value 
depending on the type of its argument. 
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NAME 

asin, dasin — Fortran arcsine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = asin(rl) 

dp2 - dasin (dpi) 
dp2 = asin(dpl) 

DESCRIPTION 

Asin returns the real arcsine of its real argument. Dasin returns 
the double-precision arcsine of its double-precision argument. The 
generic form asin may be used with impunity as it derives its type 
from that of its argument. 

SEE ALSO 

trig (3 M). 
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NAME 

atan, datan — Fortran arctangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = atan(rl) 

dp2 = datan (dpi) 
dp2 — atan(dpl) 

DESCRIPTION 

Atan returns the real arctangent of its real argument. Datan 
returns the double-precision arctangent of its double-precision 
argument. The generic form atan may be used with a double- 
precision argument returning a double-precision value. 

SEE ALSO 

trig(3M). 
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NAME 

atan2, datan2 — Fortran arctangent intrinsic function 

SYNOPSIS 

real rl, r2, r3 

double precision dpi, dp2, dp3 

r3 = atan2(rl, r2) 

dp3 = datan2(dpl, dp2) 
dp3 = atan2(dpl, dp2) 

DESCRIPTION 

Atan2 returns the arctangent of argllarg2 as a real value. Datan2 
returns the double-precision arctangent of its double-precision 
arguments. The generic form atan2 may be used with impunity 
with double-precision arguments. 

SEE ALSO 

trig (3 M). 
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NAME 

and, or, xor, not, lshift, rshift — Fortran Bitwise Boolean functions 

SYNOPSIS 

integer i, j, k 
real a, b, c 

k = and(i, j) 
c — or(a, b) 
j = xor(i, a) 
j = not(i) 
k = lshift (i, j) 
k = rshift (i, j) 

DESCRIPTION 

The generic intrinsic Boolean functions and, or and xor return the 
value of the binary operations on their arguments. Not is a unary 
operator returning the one's complement of its argument. Lshift 
and rshift return the value of the first argument shifted left or 
right, respectively, the number of times specified by the second 
(integer) argument. 

The Boolean functions are generic; that is, they are defined for all 
data types as arguments and return values. Where required, the 
compiler will generate appropriate type conversions. 

NOTE 

Although defined for all data types, use of Boolean functions on 
any but integer data is bizarre and will probably result in unex- 
pected consequences. 

BUGS 

The implementation of the shift functions may cause large shift 
values to deliver weird results. 

SEE ALSO 

mil(3F). 
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NAME 

conjg, dconjg — Fortran complex conjugate intrinsic function 

SYNOPSIS 

complex cxl, cx2 
double complex dxl, dx2 

cx2 = conjg(cxl) 

dx2 = dconjg (dxl) 

DESCRIPTION 

Conjg returns the complex conjugate of its complex argument. 
Dconjg returns the double-complex conjugate of its double- 
complex argument. 
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NAME 

cos, dcos, ccos — Fortran cosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = cos(rl) 

dp2 — dcos (dpi) 
dp2 = cos (dpi) 

cx2 = ccos(cxl) 
cx2 = cos (cxl) 

DESCRIPTION 

Cos returns the real cosine of its real argument. Dcos returns the 
double-precision cosine of its double-precision argument. Ccos 
returns the complex cosine of its complex argument. The generic 
form cos may be used with impunity as its returned type is deter- 
mined by that of its argument. 

SEE ALSO 

trig(3M). 
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NAME 

cosh, dcosh — Fortran hyperbolic cosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = cosh(rl) 

dp2 = dcosh(dpl) 
dp2 = cosh (dpi) 

DESCRIPTION 

Cosh returns the real hyperbolic cosine of its real argument. 
Dcosh returns the double-precision hyperbolic cosine of its 
double-precision argument. The generic form cosh may be used to 
return the hyperbolic cosine in the type of its argument. 

SEE ALSO 

sinh(3M). 
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NAME 

dim, ddim, idim — positive difference intrinsic functions 

SYNOPSIS 

integer al, a2, a3 
a3 = idim (a 1, a2) 

real al, a2, a3 
a3 = dim(al, a2) 

double precision al, a2, a3 
a3 = ddim (a 1, a2) 

DESCRIPTION 

These functions return: 

al-a2 if al > a2 
0 if al <- a2 
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NAME 

dprod — double precision product intrinsic function 

SYNOPSIS 

real al, a2 

double precision a3 

a3 = dprod (al, a2) 
DESCRIPTION 

Dprod returns the double precision product of its real arguments. 
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NAME 

exp, dexp, cexp — Fortran exponential intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 — exp(rl) 

dp2 = dexp(dpl) 
dp2 — exp(dpl) 

cx2 = cexp(cxl) 
cx2 — exp (cxl) 

DESCRIPTION 

Exp returns the real exponential function e x of its real argument. 
Dexp returns the double-precision exponential function of its 
double-precision argument. Cexp returns the complex exponential 
function of its complex argument. The generic function exp 
becomes a call to dexp or cexp as required, depending on the type 
of its argument. 

SEE ALSO 

exp(3M). 
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NAME 

int, ifix, idint, real, float, sngl, dble, cmplx, dcmplx, ichar, char — 
explicit Fortran type conversion 

SYNOPSIS 

integer i, j 
real r, s 

double precision dp, dq 
complex cx 
double complex dcx 
character* 7 ch 



i — 


int(r) 


i — 


int(dp) 


i = 


int(cx) 


i = 


int (dcx) 


i = 


ifix(r) 


i = 


idint (dp) 


r = 


real(i) 


r = 


real (dp) 


r = 


real(cx) 


r = 


real (dcx) 


r = 


float(i) 


r = 


sngl (dp) 


ap 


= HhlpfO 
UUlcVl/ 


dp ■ 


= dble(r) 


dp • 


= dble(cx) 


dp ■ 


= dble(dcx) 


CX ! 


= cmplx (i) 


CX ! 


= cmplx (i, j) 


CX ! 


= cmplx (r) 


CX ! 


= cmplx (r, s) 


CX ! 


■ cmplx (dp) 




— cmplx (dp, dq) 


cx ■• 


= cmplx (dcx) 


dcx 


— dcmplx (i) 


dcx 


= dcmplx (i, p 


dcx 


= dcmplx (r) 


dcx 


= dcmplx(r, s) 


dcx 


— dcmplx (dp) 


dcx 


= dcmplx (dp, d 


dcx 


= dcmplx (cx) 
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i = ichar(ch) 
ch — char(i) 

DESCRIPTION 

These functions perform conversion from one data type to another. 

The function int converts to integer form its real, double precision, 
complex, or double complex argument. If the argument is real or 
double precision, int returns the integer whose magnitude is the 
largest integer that does not exceed the magnitude of the argument 
and whose sign is the same as the sign of the argument (i.e. trun- 
cation). For complex types, the above rule is applied to the real 
part, ifix and idint convert only real and double precision argu- 
ments respectively. 

The function real converts to real form an integer, double preci- 
sion, complex, or double complex argument. If the argument is 
double precision or double complex, as much precision is kept as 
is possible. If the argument is one of the complex types, the real 
part is returned, float and sngl convert only integer and double 
precision arguments respectively. 

The function dble converts any integer, real, complex, or double 
complex argument to double precision form. If the argument is of 
a complex type, the real part is returned. 

The function cmplx converts its integer, real, double precision, or 
double complex argument (s) to complex form. 

The function dcmplx converts to double complex form its integer, 
real, double precision, or complex argument (s). 

Either one or two arguments may be supplied to cmplx and 
dcmplx . If there is only one argument, it is taken as the real part 
of the complex type and an imaginary part of zero is supplied. If 
two arguments are supplied, the first is taken as the real part and 
the second as the imaginary part. 

The function ichar converts from a character to an integer depend- 
ing on the character's position in the collating sequence. 

The function char returns the character in the z'th position in the 
processor collating sequence where / is the supplied argument. 
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For a processor capable of representing n characters, 

ichar(charG)) — i for 0 < i < «, and 

char(ichar(ch)) = ch for any representable character ch. 
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NAME 

getarg — return Fortran command-line argument 

SYNOPSIS 

character»N c 
integer i 

call getarg (i, c) 

DESCRIPTION 

Getarg returns the i-th command-line argument of the current 
process. Thus, if a program were invoked via 

foo argl arg2 arg3 

getarg(2, c) would return the string "arg2" in the character vari- 
able c. 

SEE ALSO 

getopt(3C). 
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NAME 

getenv — return Fortran environment variable 

SYNOPSIS 

character*N c 

call getenv ("VARLABLENAM E", c) 
DESCRIPTION 

Getenv returns the character-string value of the environment vari- 
able represented by its first argument into the character variable of 
its second argument. If no such environment variable exists, all 
blanks will be returned. 

SEE ALSO 

getenvOO, environ (5). 
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NAME 

iargc — return the number of command line arguments 

SYNOPSIS 

integer i 

i = iargc ( ) 
DESCRIPTION 

The iargc function returns the number of command line arguments 
passed to the program. Thus, if a program were invoked via 

foo argl arg2 arg3 

iargc ( ) would return 3. 

SEE ALSO 

getarg(3F). 
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NAME 

index — return location of Fortran substring 

SYNOPSIS 

character*Nl chl 
character*N2 ch2 
integer i 

i = index(chl, ch2) 
DESCRIPTION 

Index returns the location of substring ch2 in string chl. The 
value returned is the position at which substring ch2 starts, or 0 if 
it is not present in string chl. If N2 is greater than Nl, a zero is 
returned. 
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NAME 

len — return length of Fortran string 

SYNOPSIS 

character*N ch 
integer i 

i = len(ch) 

DESCRIPTION 

Len returns the length of string ch. 



UNIX Programmer's Manual 



System Calls and Library Routines— 305 



LOG(3F) 



LOG(3F) 



NAME 

log, alog, dlog, clog — Fortran natural logarithm intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = alog(rl) 
r2 = log(rl) 

dp2 = dlog(dpl) 
dp2 - log(dpl) 

cx2 = clog(cxl) 
cx2 = log(cxl) 

DESCRIPTION 

Alog returns the real natural logarithm of its real argument. Dlog 
returns the double-precision natural logarithm of its double- 
precision argument. Clog returns the complex logarithm of its 
complex argument. The generic function log becomes a call to 
alog, dlog, or clog depending on the type of its argument. 

SEE ALSO 

exp(3M). 
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NAME 

log 10, aloglO, dloglO — Fortran common logarithm intrinsic func- 
tion 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 - aloglO(rl) 
r2 - loglO(rl) 

dp2 - dloglO(dpl) 
dp2 = loglO(dpl) 

DESCRIPTION 

AloglO returns the real common logarithm of its real argument. 
DloglO returns the double-precision common logarithm of its 
double-precision argument. The generic function loglO becomes a 
call to aloglO or dloglO depending on the type of its argument. 

SEE ALSO 

exp(3M). 



UNIX Programmer's Manual 



System Calls and Library Routines— 307 



MAX(3F) 



MAX(3F) 



NAME 

max, maxO, amaxO, maxl, amaxl, dmaxl — Fortran maximum- 
value functions 

SYNOPSIS 

integer i, j, k, 1 
real a, b, c, d 

double precision dpi, dp2, dp3 

1 = max(i, j, k) 
c = max (a, b) 
dp = max (a, b, c) 
k = maxO(i, j) 
a — amaxOG, j, k) 
i = maxl (a, b) 
d = amaxl (a, b, c) 
dp3 = dmaxl (dpi, dp2) 

DESCRIPTION 

The maximum-value functions return the largest of their argu- 
ments (of which there may be any number). Max is the generic 
form which can be used for all data types and takes its return type 
from that of its arguments (which must all be of the same type). 
MaxO returns the integer form of the maximum value of its 
integer arguments; amaxO, the real form of its integer arguments; 
maxl, the integer form of its real arguments; amaxl, the real 
form of its real arguments; and dmaxl, the double-precision form 
of its double-precision arguments. 

SEE ALSO 

min(3F). 
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NAME 

mclock — return Fortran time accounting 

SYNOPSIS 

integer i 

i — mclock ( ) 

DESCRIPTION 

Mclock returns time accounting information about the current 
process and its child processes. The value returned is the sum of 
the current process's user time and the user and system times of 
all child processes. 

SEE ALSO 

times (2), clock(3C), system (3F). 
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NAME 

ior, iand, not, ieor, ishft, ishftc, ibits, btest, ibset, ibclr, mvbits — 
bit field manipulation intrinsic functions and subroutines from the 
Fortran Military Standard (MIL-STD-1753). 

SYNOPSIS 

integer i, k, 1, m, n, len 
logical b 



i = 


ior(m, n) 


i = 


iand(m, n) 


i = 


not(m) 


i — 


ieorGn, n) 


i = 


ishft (m, k) 




ishftc (m, k, len) 


i = 


ibits (m, k, len) 


b = 


btest (n, k) 


i = 


ibset (n, k) 


i = 


ibclr (n, k) 


call 


mvbits (m, k, len, n, 1) 



DESCRIPTION 

ior, iand, not, ieor — return the same results as and, or, not, xor 
as defined in bool (3 F). 

ishft, ishftc — m specifies the integer to be shifted, k specifies the 
shift count, k > 0 indicates a left shift, k = 0 indicates no shift, 
k < 0 indicates a right shift. In ishft, zeros are shifted in. In 
ishftc, the rightmost len bits are shifted circularly k bits. If k is 
greater than the machine word-size, ishftc will not shift. 

Bit fields are numbered from right to left and the rightmost bit 
position is zero. The length of the len field must be greater than 
zero. 

ibits — extract a subfield of len bits from m starting with bit posi- 
tion k and extending left for len bits. The result field is right 
justified and the remaining bits are set to zero. 

btest — The kth bit of argument n is tested. The value of the 
function is .TRUE, if the bit is 1 and .FALSE, if the bit is 0. 

ibset — the result is the value of n with the kth bit set to 1 . 

ibclr — the result is the value of n with the kth bit set to 0. 
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mvbits — len bits are moved beginning at position k of argument m 
to position 1 of argument n. 

SEE ALSO 

bool(3f). 
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NAME 

min, minO, aminO, mini, aminl, dminl — Fortran minimum-value 
functions 

SYNOPSIS 

integer i, j, k, 1 
real a, b, c, d 

double precision dpi, dp2, dp3 

1 = min(i, j, k) 
c — min (a, b) 
dp — min (a, b, c) 
k — minO(i, j) 
a = aminOO, j, k) 
i = mini (a, b) 
d = aminl (a, b, c) 
dp3 — dminl (dpi, dp2) 

DESCRIPTION 

The minimum-value functions return the minimum of their argu- 
ments (of which there may be any number). Min is the generic 
form which can be used for all data types and takes its return type 
from that of its arguments (which must all be of the same type). 
MinO returns the integer form of the minimum value of its integer 
arguments; aminO, the real form of its integer arguments; mini, 
the integer form of its real arguments; aminl , the real form of its 
real arguments; and dminl, the double-precision form of its 
double-precision arguments. 

SEE ALSO 

max(3F). 
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NAME 

mod, amod, dmod — Fortran remaindering intrinsic functions 

SYNOPSIS 

integer i, j, k 
real rl, r2, r3 

double precision dpi, dp2, dp3 

k Ba mod(i, j) 

r3 = amod(rl, r2) 
r3 - mod(rl, r2) 

dp3 — dmod (dpi, dp2) 
dp3 — mod (dpi, dp2) 

DESCRIPTION 

Mod returns the integer remainder of its first argument divided by 
its second argument. Amod and dmod return, respectively, the 
real and double-precision whole number remainder of the integer 
division of their two arguments. The generic version mod will 
return the data type of its arguments. 
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NAME 

irand, rand, srand — random number generator 

SYNOPSIS 

integer iseed, i, irand 
double precision x, rand 



call srand (iseed) 
i — irand ( ) 
x = rand( ) 
DESCRIPTION 

Irand generates successive pseudo-random integers in the range 
from 0 to 2**15—1. Rand generates pseudo-random numbers dis- 
tributed in [0, 1.0]. Srand uses its integer argument to re- 
initialize the seed for successive invocations of irand and rand. 

SEE ALSO 

rand(3C). 
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NAME 

anint, dnint, nint, idnint — Fortran nearest integer functions 

SYNOPSIS 

integer i 
real rl, r2 

double precision dpi, dp2 

r2 = anint(rl) 
i = nint(rl) 

dp2 = anint (dpi) 
dp2 = dnint(dpl) 

i = nint (dpi) 
i = idnint(dpl) 

DESCRIPTION 

Anint returns the nearest whole real number to its real argument 
(i.e., int(a+0.5) if a > 0, int(a— 0.5) otherwise). Dnint does the 
same for its double-precision argument. Nint returns the nearest 
integer to its real argument. Idnint is the double-precision version. 
Anint is the generic form of anint and dnint , performing the same 
operation and returning the data type of its argument. Nint is 
also the generic form of idnint. 
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NAME 

sign, isign, dsign — Fortran transfer-of-sign intrinsic function 

SYNOPSIS 

integer i, j, k 
real rl, r2, r3 

double precision dpi, dp2, dp3 

k = isign (i, j) 
k = sign(i, j) 

r3 = sign(rl, r2) 

dp3 = dsign(dpl, dp2) 
dp3 = sign (dpi, dp2) 

DESCRIPTION 

Isign returns the magnitude of its first argument with the sign of 
its second argument. Sign and dsign are its real and double- 
precision counterparts, respectively. The generic version is sign 
and will devolve to the appropriate type depending on its argu- 
ments. 
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NAME 

signal — specify Fortran action on receipt of a system signal 

SYNOPSIS 

integer i, intfc 
external intfc 

call signal (i, intfc) 

DESCRIPTION 

The argument i specifies the signal to be caught. Signal allows a 
process to specify a function to be invoked upon receipt of a 
specific signal. The first argument specifies which fault or excep- 
tion. The second argument specifies the function to be invoked. 
NOTE: The interrupt processing function, intfc, does not take an 
argument. 

SEE ALSO 

kill (2), signal (2). 
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NAME 

sin, dsin, csin — Fortran sine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = sin(rl) 

dp2 = dsin(dpl) 
dp2 = sin(dpl) 

cx2 = csin(cxl) 
cx2 = sin(cxl) 

DESCRIPTION 

Sin returns the real sine of its real argument. Dsin returns the 
double-precision sine of its double-precision argument. Csin 
returns the complex sine of its complex argument. The generic sin 
function becomes dsin or csin as required by argument type. 

SEE ALSO 

trig(3M). 
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NAME 

sinh, dsinh — Fortran hyperbolic sine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = sinh(rl) 

dp2 = dsinh(dpl) 
dp2 = sinh (dpi) 

DESCRIPTION 

Sinh returns the real hyperbolic sine of its real argument. Dsinh 
returns the double-precision hyperbolic sine of its double-precision 
argument. The generic form sinh may be used to return a 
double-precision value when given a double-precision argument. 

SEE ALSO 

sinh (3 M). 
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NAME 

sqrt, dsqrt, csqrt — Fortran square root intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = sqrt(rl) 

dp2 = dsqrt(dpl) 
dp2 = sqrt (dpi) 

cx2 = csqrt(cxl) 
cx2 — sqrt (cxl) 

DESCRIPTION 

Sqrt returns the real square root of its real argument. Dsqrt 
returns the double-precision square root of its double-precision 
argument. Csqrt returns the complex square root of its complex 
argument. Sqrt, the generic form, will become dsqrt or csqrt as 
required by its argument type. 

SEE ALSO 

exp(3M). 
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NAME 

lge, lgt, lie, lit — string comparison intrinsic functions 

SYNOPSIS 

character*N al, a2 
logical 1 

1 = lge(al, a2) 

1 - lgt(al, a2) 

1 = Ue(al, a2) 

1 = llt(al, a2) 

DESCRIPTION 

These functions return .TRUE, if the inequality holds and .FALSE, 
otherwise. 
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NAME 

system — issue a shell command from Fortran 

SYNOPSIS 

character*N c 

call system (c) 

DESCRIPTION 

System causes its character argument to be given to sh(\) as 
input, as if the string had been typed at a terminal. The current 
process waits until the shell has completed. 

SEE ALSO 

exec(2), system (3S). 

sh(l) in the UNIX Programmer's Manual —Volume 1: Commands 
and Utilities. 



322— System Calls and Library Routines 



UNIX Programmer's Manual 



TAN(3F) 



TAN(3F) 



NAME 

tan, dtan — Fortran tangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = tan(rl) 

dp2 = dtan(dpl) 
dp2 = tan(dpl) 

DESCRIPTION 

Tan returns the real tangent of its real argument. Dtan returns 
the double-precision tangent of its double-precision argument. The 
generic tan function becomes dtan as required with a double- 
precision argument. 

SEE ALSO 

trig(3M). 
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NAME 

tanh, dtanh — Fortran hyperbolic tangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = tanh(rl) 

dp2 - dtanh(dpl) 
dp2 = tanh(dpl) 

DESCRIPTION 

Tanh returns the real hyperbolic tangent of its real argument. 
Dtanh returns the double-precision hyperbolic tangent of its 
double-precision argument. The generic form tanh may be used to 
return a double-precision value given a double-precision argument. 

SEE ALSO 

sinh(3M). 
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NAME 

intro — introduction to file formats 
DESCRIPTION 

This section outlines the formats of various files. The C struct 
declarations for the file formats are given where applicable. Usu- 
ally, these structures can be found in the directories /usr/include 
or /usr/include/sys. 

References of the type name (1M) refer to entries found in Section 
1 of the UNIX Programmer's Manual— Volume 3: System 
Administration Facilities. References of the type Named) refer 
to entries found in Section 1 of the UNIX Programmer's 
Manual —Volume 1: Commands and Utilities. 
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NAME 

a.out — common assembler and link editor output 
DESCRIPTION 

The file name a.out is the output file from the assembler as (I) and 
the link editor Id (I). Both programs will make a.out executable if 
there were no errors in assembling or linking and no unresolved 
external references. 

A common object file consists of a file header, a UNIX system 
header, a table of section headers, relocation information, 
(optional) line numbers, a symbol table, and a string table. The 
order is given below. 

File header. 

UNIX system header. 

Section 1 header. 

Section n header. 
Section 1 data. 

Section n data. 
Section 1 relocation. 

Section n relocation. 
Section 1 line numbers. 

Section n line numbers. 
Symbol table. 
String table. 

The last three parts of an object file (line numbers, symbol table, 
and string table) may be missing if the program was linked with 
the — s option of ld(\) or if they were removed by strip (I). Also 
note that the relocation information will be absent if there were no 
unresolved external references after linking. The string table exists 
only if the symbol table contains symbols with names longer than 
eight characters. 

The sizes of each section (contained in the header, discussed 
below) are in bytes and are even. 

When an a.out file is loaded into memory for execution, three logi- 
cal segments are set up: the text segment, the data segment (ini- 
tialized data followed by uninitialized, the latter actually being 
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initialized to all O's), and a stack. On the 3B20 computers and 
other machines the text segment starts at location 0 in the core 
image or at the beginning of the next virtually addressable block 
past location 0. Any reference to 0 causes a memory fault (see the 
— z option of Id (I). On the 3B5 or 3B2 computers the text seg- 
ment starts at location 0x80800000. 

The a.out file produced by Id (I) by default has a number called 
the magic number 0413 in the first field of the UNIX system 
header. The headers (file header, UNIX system header, and sec- 
tion headers) are loaded at the beginning of the text segment and 
the text immediately follows the headers in the user address space. 
The first text address will equal the size of the headers, and will 
vary depending upon the number of section headers in the a.out 
file. 

In an a.out file with three sections (.text, .data, and .bss), the first 
text address is at 0xA8 on most machines, OxBO on the 3B20 com- 
puter, and 0x808000A8 on the 3B5 computer and 3B2 computer. 
The text segment is not writable by the program; if other processes 
are executing the same a.out file, the processes will share a single 
text segment. 

The data segment starts at the next segment boundary (128k on 
the 3B20, 512k on the 3B5 and 3B2 computers) past the last text 
address. The first data address is determined by the following: If 
an a.out file were split into 8k chunks, one of the chunks would 
contain both the end of text and the beginning of data. When the 
core image is created, that chunk will appear twice; once at the 
end of text and once at the beginning of data (with some unused 
space in between). The duplicated chunk of text that appears at 
the beginning of data is never executed; it is duplicated so that the 
operating system may bring in pieces of the file in multiples of the 
page size without having to realign the beginning of the data sec- 
tion to a page boundary. Therefore the first data address is the 
sum of the next segment boundary past the end of text plus the 
remainder of the last text address divided by 8k. 

On the 3B20 computer a magic number of 0410 or 0407 in the 
UNIX system header indicates that the file was produced by a link 
editor from an earlier release of the UNIX system. An a.out file 
with either of these magic numbers will still be executable, 
although support for files with the magic number 0407 may be 
dropped in a future release. The magic number 0407 indicates 
that the text segment is not write-protected or shared, and the 
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data segment is contiguous with the text segment. If the magic 
number is 0410, the text segment is write-protected and sharable. 
In both of these types of a.out files, the header is not loaded; the 
text segment starts at location 0 in the core image. 

On the 3B20 computer, the stack begins at the end of the data sec- 
tion and grows toward higher addresses. On the 3B2 computer the 
stack begins at location 0x00020000 and grows toward higher 
addresses. On the 3B5 computer the stack begins at location 
OxFOOOOO and grows toward higher addresses. The maximum 
stack size on the 3B5 computer is 512k. On some computers, the 
stack begins at the end of memory and grows toward lower 
addresses. On some other machines the stack is automatically 
extended as required. The data segment is extended only as 
requested by the brk(2) system call. 

The value of a word in the text or data portions that is not a refer- 
ence to an undefined external symbol is exactly the value that will 
appear in memory when the file is executed. If a word in the text 
involves a reference to an undefined external symbol, the storage 
class of the symbol-table entry for that word will be marked as an 
"external symbol", and the section number will be set to 0. When 
the file is processed by the link editor and the external symbol 
becomes defined, the value of the symbol will be added to the word 
in the file. 

File Header 

The format of the filehdr header is 



struct filehdr 



{ 



unsigned short 
unsigned short 
long 



unsigned short 
unsigned short 



long 
long 



fmagic; 

fnscns; 

ftimdat; 

fjsymptr; 

f_nsyms; 

fopthdr; 

fflags; 



/* magic number */ 
/* number of sections */ 
/* time and date stamp */ 
/* file ptr to symtab */ 
/* # symtab entries */ 
/* sizeof(opt hdr) */ 
/* flags */ 



}; 
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UNIX System Header 

The format of the UNIX system header on all machines other than 
the 3B20 computer is 

typedef struct aouthdr 
{ 



short 


magic; 


/* 


magic number */ 


short 


vstamp; 


/* 


version stamp */ 


long 


tsize; 


/* 


text size in bytes, padded */ 


long 


dsize; 


/* 


initialized data (.data) */ 


long 


bsize; 


/* 


uninitialized data Cbss) */ 


long 


entry; 


/* 


entry point */ 


long 


text_start; 


/• 


base of text used for this file */ 


long 


datastart; 


/• 


base of data used for this file */ 



} AOUTHDR; 

The format of the 3B20 computer UNIX system header is 

typedef struct aouthdr 
{ 



short 


magic; 


/* 


magic number */ 


short 


vstamp; 


/* 


version stamp */ 


long 


tsize; 


/* 


text size in bytes, padded */ 


long 


dsize; 


/* 


initialized data (.data) */ 


long 


bsize; 


/* 


uninitialized data Cbss) */ 


long 


duml; 


/* 


unused fill space included */ 


long 


dum2; 


/* 


for historical reasons */ 


long 


entry; 


/• 


entry point */ 


long 


text_start; 


/* 


base of text used for this file */ 


long 


datastart; 


/* 


base of data used for this file */ 



} AOUTHDR; 
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Section Header 



The format of the section header is 



struct scnhdr 



{ 

char s_name[SYMNMLEN];/* section name */ 

long s_paddr; /* physical address */ 

long s vaddr; /* virtual address */ 

long s size; /* section size */ 

long s_scnptr; /* file ptr to raw data */ 

long srelptr; /* file ptr to relocation */ 

long s lnnoptr; /* file ptr to line numbers */ 

unsigned short s nreloc; /* # reloc entries */ 

unsigned short s nlnno; /* # line number entries */ 

long s flags; /* flags */ 



}; 



Relocation 

Object files have one relocation entry for each relocatable refer- 
ence in the text or data. If relocation information is present, it 
will be in the following format: 

struct reloc 



The start of the relocation information is sjelptr from the section 
header. If there is no relocation information, s relptr is 0. 
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long 
long 
short 



r vaddr; /* (virtual) address of reference */ 
rsymndx; /* index into symbol table */ 
r_type; /* relocation type */ 



}; 
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Symbol Table 

The format of each symbol in the symbol table is 

#define SYMNMLEN 8 
#define FILNMLEN 14 

#define SYMESZ 18 /* the size of a SYMENT */ 



struct syment 
{ 

union 
{ 

char 

struct 

{ 

long 
long 

} _n_n; 

char 

}_n; 

unsigned long 
short 

unsigned short 

char 

char 

}; 



/* get a symbol name */ 
n namel SYMNMLEN 1; /* name of symbol */ 



nzeroes; /* == OL if in string table */ 

noffset; /* location in string table */ 

*_n_nptr[2l; /* allows overlaying */ 

n_value; /* value of symbol */ 

njscnum; /* section number */ 

n_type; /* type and derived type */ 

n_sclass; /* storage class */ 

n numaux; /* number of aux entries */ 



#define n name 

#define n zeroes 

#define n offset 

#define n nptr 



n.nname 
_n._n_n._n_zeroes 
_n._n_n._n_offset 
_n._n_nptr[l] 



Some symbols require more information than a single entry; they 
are followed by auxiliary entries that are the same size as a sym- 
bol entry. The format follows. 
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union auxent { 
struct { 

long xtagndx; 
union { 

struct { 

unsigned short xjnno; 
unsigned short x_size; 

} xjnsz; 

long xfsize; 
} x misc; 
union { 

struct { 

long xjnnoptr; 
long x_endndx; 

} x fcn; 
struct { 

unsigned short x_dimen[DIMNUM]; 

} x_ary; 
} x_fcnary; 

unsigned short xjtvndx; 
} x_sym; 

struct { 

char x_fname[FILNMLEN]; 
} x file; 

struct { 

long xscnlen; 

unsigned short x nreloc; 

unsigned short x nlinno; 
} x_scn; 

struct { 

long xtvfill; 

unsigned short x tvlen; 

unsigned short x_tvran[2]; 

} x_tv; 

}; 
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Indexes of symbol table entries begin at zero. The start of the 
symbol table is fjymptr (from the file header) bytes from the 
beginning of the file. If the symbol table is stripped, fjymptr is 0. 
The string table (if one exists) begins at fjymptr + ifjisyms * 
SYMESZ) bytes from the beginning of the file. 

SEE ALSO 

brk(2), filehdr(4), ldfcn(4), linenum(4), reloc(4), scnhdr(4), 
syms(4). 

as(l), cc(l), ld(l) in the UNIX Programmer's Manual —Volume 
1: Commands and Utilities. 
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NAME 

acct — per-process accounting file format 

SYNOPSIS 

#include <sys/acct.h> 

DESCRIPTION 

Files produced as a result of calling acct (2) have records in the 
form defined by <sys/acct.h>, whose contents are: 

typedef ushort compt; /* "floating point" */ 

/* 13-bit fraction, 3-bit exponent */ 



struct acct 
{ 

char ac flag; /* Accounting flag */ 

char ac stat; /* Exit status */ 

ushort acuid; 

ushort acjgid; 

devt actty; 

timej acbtime; /* Beginning time */ 

compjt acjutime; /* acctng user time in clock ticks */ 

comp_t acstime; /* acctng system time in clock ticks */ 

comp_t ac_etime; /* acctng elapsed time in clock ticks */ 

comp t acjmem; /* memory usage in clicks */ 

comp t ac io; /* chars trnsfrd by read/write */ 

comp t acrw; /* number of block reads/writes •/ 

char ac_comm[8]; /* command name */ 

}; 



extern struct acct acctbuf; 

extern struct inode *acctp; /* inode of accounting file */ 

#define AFORK 01 /* has executed fork, but no exec •/ 

#define ASU 02 /* used super-user privileges */ 

#define ACCTF 0300 /* record type: 00 - acct */ 

In ac Jlag, the AFORK flag is turned on by each fork (2) and 
turned off by an execil). The ac comm field is inherited from the 
parent process and is reset by any exec. Each time the system 
charges the process with a clock tick, it also adds to acjnem the 
current process size, computed as follows: 

(data size) + (text size) / (number of in-core processes using text) 
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The value of acmem I (acjtime + acutime) can be viewed as an 
approximation to the mean process size, as modified by text- 
sharing. 

The structure tacct.h, which resides with the source files of the 
accounting commands, represents the total accounting format used 
by the various accounting commands: 

/* 

* total accounting (for acct period), also for day 
*/ 

struct tacct { 



uid t tauid; /* userid */ 

char ta_name[8]; /* login name */ 

float ta_cpu[2l; /* cum. cpu time, p/np (mins) */ 

float ta_kcore[2]; /* cum kcore-minutes, p/np */ 

float ta_con[2l; /* cum. connect time, p/np, mins */ 

float ta du; /* cum. disk usage */ 

long tajpc; /* count of processes */ 



unsigned short ta sc; /* count of login sessions */ 
unsigned short ta dc; /* count of disk samples */ 
unsigned short ta_fee; /* fee for special services */ 

}; 

SEE ALSO 

acct (2), exec (2), fork(2). 

acct(lM) in the UNIX Programmer's Manual —Volume 3: Sys- 
tem Administration Facilities. 

acctcom(l) in the UNIX Programmer's Manual —Volume 1: 
Commands and Utilities. 

BUGS 

The ac mem value for a short-lived command gives little informa- 
tion about the actual size of the command, because acjnem may 
be incremented while a different command (e.g., the shell) is being 
executed by the process. 
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NAME 

ar — common archive file format 
DESCRIPTION 

The archive command aril) is used to combine several files into 
one. Archives are used mainly as libraries to be searched by the 
link editor Id (l). 

Each archive begins with the archive magic string. 

#define ARMAG "!<arch>\n" /* magic string */ 

#define SARMAG 8 /* length of magic string */ 

Each archive which contains common object files (see a.out(4)) 
includes an archive symbol table. This symbol table is used by the 
link editor Id (I) to determine which archive members must be 
loaded during the link edit process. The archive symbol table (if it 
exists) is always the first file in the archive (but is never listed) 
and is automatically created and/or updated by ar. 

Following the archive magic string are the archive file members. 
Each file member is preceded by a file member header which is of 
the following format: 

#define ARFMAG '"\n" /• header trailer string */ 

struct ar hdr /* file member header */ 



All information in the file member headers is in printable ASCII. 
The numeric information contained in the headers is stored as 
decimal numbers (except for arjnode which is in octal). Thus, if 
the archive contains printable files, the archive itself is printable. 

The arjiame field is blank-padded and slash (/) terminated. The 
ar date field is the modification date of the file at the time of its 



{ 



char 
char 
char 
char 
char 
char 
char 



ar_name[16]; 

ar_date[12]; 

ar_uid[6l; 

ar _gid[6]; 

ar_mode[8]; 

ar_size[10]; 

ar_fmag[2l; 



/* V terminated file member */ 

/* file member date */ 

/* file user identification */ 

/* file group identification */ 

/* file member mode (octal) */ 

/* file member size */ 

/* header trailer string */ 



}; 
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insertion into the archive. Common format archives can be moved 
from system to system as long as the portable archive command 
ar(l) is used. Conversion tools such as convert (l) exist to aid in 
the transportation of non-common format archives to this format. 

Each archive file member begins on an even byte boundary; a new- 
line is inserted between files if necessary. Nevertheless the size 
given reflects the actual size of the file exclusive of padding. 

Notice there is no provision for empty areas in an archive file. 

If the archive symbol table exists, the first file in the archive has a 
zero length name (i.e., ar namelOl == V). The contents of this 
file are as follows: 

• The number of symbols. Length: 4 bytes. 

• The array of offsets into the archive file. Length: 4 bytes 
* "the number of symbols". 

• The name string table. Length: arjsize — (4 bytes * 
("the number of symbols" + 1)). 

The number of symbols and the array of offsets are managed with 
sgetl and sputl. The string table contains exactly as many null 
terminated strings as there are elements in the offsets array. Each 
offset from the array is associated with the corresponding name 
from the string table (in order). The names in the string table are 
all the defined global symbols found in the common object files in 
the archive. Each offset is the location of the archive header for 
the associated symbol. 

SEE ALSO 

sputl (3X), a.out(4). 

ar(l), convert (1), ld(l), strip(l) in the UNIX Programmer's 
Manual —Volume 1: Commands and Utilities. 

CAVEATS 

The common archive structure is not compatible between the 
PDP-11 and the IBM-370, due to the different file formats. See 
convert (1) to convert between machines. 

Strip (1) will remove all archive symbol entries from the header. 
The archive symbol entries must be restored via the ts option of 
the ar{\) command before the archive can be used with the link 
editor Id (I). 
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NAME 

checklist — list of file systems processed by fsck 
DESCRIPTION 

Checklist resides in directory /etc and contains a list of, at most, 
15 special file names. Each special file name is contained on a 
separate line and corresponds to a file system. Each file system 
will then be automatically processed by the fsck (1M) command. 

SEE ALSO 

fsck(lM) in the UNIX Programmer's Manual —Volume 3: System 
Administration Facilities. 
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NAME 

core — format of core image file 
DESCRIPTION 

The UNIX system writes out a core image of a terminated process 
when any of various errors occur. See signal (2) for the list of rea- 
sons; the most common are memory violations, illegal instructions, 
bus errors, and user-generated quit signals. The core image is 
called core and is written in the process's working directory (pro- 
vided it can be; normal access controls apply). A process with an 
effective user ID different from the real user ID will not produce a 
core image. 

The first section of the core image is a copy of the system's per- 
user data for the process, including the registers as they were at 
the time of the fault. The size of this section depends on the 
parameter usize, which is defined in /usr/include/sys/param.h. 
The remainder represents the actual contents of the user's core 
area when the core image was written. If the text segment is 
read-only and shared, or separated from data space, it is not 
dumped. 

The format of the information in the first section is described by 
the user structure of the system, defined in 
/usr/inchide/sys/user.h. The important stuff not detailed therein 
is the locations of the registers, which are outlined in 
/usr/include/sys/reg.h. 

SEE ALSO 

setuid(2), signal (2). 

crash(lM) in the UNIX Programmer's Manual —Volume 3: Sys- 
tem Administration Facilities. 

sdb(l) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
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NAME 

cpio — format of cpio archive 
DESCRIPTION 

The header structure, when the — c option of cpio (l) is not used, 

is: 

struct { 

short hmagic, 

hjdev; 
ushort hino, 

hjnode, 

huid, 

hjgid; 
short hnlink, 

h_rdev, 

h_mtime[2], 

hjiamesize, 

h_filesize[2];. 
char h_name[h_namesize rounded to word]; 

} Hdr; 

When the —c option is used, the header information is described 
by: 

sscanf (Chdr,"%6o%6o%6o%6o%6o%6o%6o%6o% 1 1 lo%6o% 1 1 lo%s", 
&Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode, 
&Hdr.h_uid, &Hdr.h jgid, &Hdr.h_nlink, &Hdr.hj-dev, 
&Longtime, &Hdr.h_namesize,&Longfile,Hdr.h_name) ; 

Longtime and Longfile are equivalent to Hdr.hjntime and 
Hdr.h Jilesize, respectively. The contents of each file are recorded 
in an element of the array of varying length structures, archive, 
together with other items describing the file. Every instance of 
hjnagic contains the constant 070707 (octal). The items hdev 
through hjntime have meanings explained in stat (2) . The length 
of the null-terminated path name hjiame, including the null byte, 
is given by hjiamesize. 

The last record of the archive always contains the name 
TRAILER!!!. Special files, directories, and the trailer are recorded 
with h Jilesize equal to zero. 
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SEE ALSO 

stat (2). 

cpio(l), find(l) in the UNIX Programmer's Manual —Volume 1: 
Commands and Utilities. 
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NAME 

dir — format of directories 

SYNOPSIS 

#include <sys/dir.h> 

DESCRIPTION 

A directory behaves exactly like an ordinary file, save that no user 
may write into a directory. The fact that a file is a directory is 
indicated by a bit in the flag word of its i-node entry (see /s(4)). 
The structure of a directory entry as given in the include file is: 

#ifndef DIRSIZ 
#define DIRSIZ 14 
#endif 

struct direct 
{ 

ino t d ino; 

char dnametDIRSIZ]; 

}; 

By convention, the first two entries in each directory are for . and 
... The first is an entry for the directory itself. The second is for 
the parent directory. The meaning of .. is modified for the root 
directory of the master file system; there is no parent, so . . has the 
same meaning as .. 

SEE ALSO 

fs(4). 
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NAME 



errfile — error-log file format 



DESCRIPTION 

When hardware errors are detected by the system, an error record 
is generated and passed to the error-logging daemon for recording 
in the error log for later analysis. The default error log is 
/usr/adm/errfile. 

The format of an error record depends on the type of error that 
was encountered. Every record, however, has a header with the 
following format: 



struct errhdr { 

short etype; 

short elen; 

timet e_time; 

int e_cpu; 

}; 

The permissible record types are as follows 



/* record type */ 
/* bytes in record (inc hdr) */ 
/* time of day */ 
/* proc recording error*/ 



#define 


E 


GOTS 


010 


/* 


start for UNIX System 










* 


Release 3.0*/ 


#define 


E. 


GORT 


Oil 


/* 


start for UNIX system/RT */ 


#define 


E_ 


STOP 


012 


/* 


stop */ 


#define 


E 


TCHG 


013 


/* 


time change */ 


#define 


E 


CCHG 


014 


/* 


configuration change */ 


#define 


E_ 


BLK 


020 


/* 


block device error */ 


#define 


E_ 


STRAY 


030 


/* 


stray interrupt */ 


#define 


E_ 


PRTY 


031 


/* 


memory parity */ 


#define 


E 


PIO 


041 


/* 


3B20 computer programmed 










* 


I/O */ 


#define 


E_ 


_IOP 


042 


/* 


3B20 computer I/O 










* 


processor */ 


#define 


E 


NI 


0100 


/* 


NI20 error */ 



Some records in the error file are of an administrative nature. 
These include the startup record that is entered into the file when 
logging is activated, the stop record that is written if the daemon is 
terminated "gracefully", and the time-change record that is used 
to account for changes in the system's time-of-day. These records 
have the following formats: 
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struct estart { 

short e_cpu; 

struct utsname ejname; 
#ifndef u3b 



/* CPU type */ 
/* system names */ 



e_mmr3; 

e_syssize; 

e_bconf; 



/* contents mem mgmt reg 3 */ 
/* 11/70 system memory size */ 
/* block dev configuration */ 



ejmmcnt; /* kbytes per array */ 



short 
long 
short 
#endif 
#ifdef u3b 

int 
#endif 
}; 

#define eend errhdr /* record header */ 

struct etimchg { 
timej 

}; 

Stray interrupts cause a record with the following format to be 
logged: 

struct estray { 
#ifdef u3b 
uint 

#else 

physadr 
short 
#endif 

}; 



e_ntime; /* new time */ 



e_saddr; /* stray loc or device addr */ 

e_saddr; /* stray loc or device addr */ 
e_sbacty; /* active block devices */ 



Memory subsystem error on 3B20 computer cause the following 
record to be generated: 

struct eparity { 
#ifdefu3b 

int ejparreg[3]; /* 3B computer memory 

* registers */ 

#else 

short ejparreg[4l; /* memory subsys registers */ 

#endif 

}; 
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Memory subsystem errors on VAX- 11/780 processors cause the fol 
lowing record to be generated: 

struct ememory { 

int esbier; 
int ememcad; 

}; 



have the following format: 



Error records for block devices 

struct eblock { 
#ifdef u3b 



ushort 


enum; 


struct iostat { 




long 


ioops; 


long 


iomisc; 


ushort 


iounlog; 


} 


estats; 


short 


ebflags; 


daddrt 


ebnum; 


uint 


e_bytes; 


union ptbl { 




int page[64]; 


union ptbl *pnext; 


J 


e_ptbl; 


struct ptbl 


e_ptbl; 


uint 


evoff; 


uint 


e_statl; 


uint 


e_stat2; 



#endif 



/* device number */ 

/* number read/ writes */ 

/* number "other" operations */ 

/* number unlogged errors */ 

/* read/write, error, etc */ 
/* logical block number */ 
/* number bytes to transfer */ 



/* page table entries */ 



/* page table for transfer */ 
/* offset into page table */ 
/* status word 1 */ 
/* status word 2 */ 
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#ifndef u3b 



dev t 


e dev; 


/• 


true major + minor dev it */ 


physadr 


e regloc; 


/* 


controller address */ 


short 


e hfictv* 


/* 


other block T/O activitv */ 


struct iostat i 








Ions 


io ops; 


/* 


number read/ writes */ 


lone 


io misc* 


/* 


number "other" operations */ 


ushort 


io_unlog; 


/♦ 


number unlogged errors */ 


} 


e_stats; 






short 


ebflags; 


/* 


read/write, error, etc */ 


short 


ecyloff; 


/* 


logical dev start cyl */ 


daddrt 


e_bnum; 


/* 


logical block number */ 


ushort 


ebytes; 


/* 


number bytes to transfer */ 


paddrt 


ememadd; 


/* 


buffer memory address */ 


ushort 


e_rtry; 


/* 


number retries */ 


short 


enreg; 


/* 


number device registers */ 



#endif 
#ifdef vax 

struct mba_regs { 

long mba_csr; 

long mba_cr; 

long mba_sr; 

long mba_var; 

long mba_vcr; 
} e mba; 
#endif 



The following values are used in the e 


'_bflags word: 


#define EWRITE 


0 


/* 


write operation */ 


#define EREAD 


1 


/* 


read operation */ 


#define E_NOIO 


02 


/* 


no I/O pending */ 


#define E_PHYS 


04 


/* 


physical I/O */ 


#define E MAP 


010 


/* 


Unibus map in use */ 


#define E ERROR 


020 


/* 


I/O failed */ 
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The following error records are for the 3B20 computer only: 

struct epio { /* programmed I/O error */ 

char e chan; /* which channel */ 

char ejdev; /* which dev on channel */ 

uint e chstat; /* channel status */ 

uint e cmd; /* pio command */ 

} 

struct eiop { /* I/O processor (iop) error */ 

char e unit; /* unit number */ 

uint e wordO; /* iop report word */ 

uint e wordl; /* iop report word */ 

} 



The "true" major device numbers that identify the failing device 
are as follows: 



Digital Equipment 


AT&T 




#define RKO 


0 


#define DFCO 


0 


#define RPO 


1 


#define IOP0 


1 


#define RFO 


2 


#define MTO 


2 


#define TMO 


3 






#define TCO 


4 






#define HPO 


5 






#define HTO 


6 






#define HSO 


7 






#define RLO 


8 






#define HP1 


9 






#define HP2 


10 






#define HP3 


11 







SEE ALSO 

errdemon(lM) in the UNIX Programmer's Manual —Volume 3: 
System Administration Facilities. 
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NAME 

filehdr — file header for common object files 

SYNOPSIS 

#include <filehdr.h> 

DESCRIPTION 

Every common object file begins with a 20-byte header. The fol- 
lowing C struct declaration is used: 

struct filehdr 
{ 

unsigned short fmagic ; /* magic number */ 
unsigned short fjiscns ; /* number of sections */ 
long ftimdat ; /* time & date stamp */ 

long f symptr ; /* file ptr to symtab */ 

long f_nsyms ; /* # symtab entries */ 

unsigned short f opthdr ; /* sizeof(opt hdr) */ 
unsigned short f flags ; /* flags */ 

}; 

Fjymptr is the byte offset into the file at which the symbol table 
can be found. Its value can be used as the offset in /seek OS) to 
position an I/O stream to the symbol table. The UNIX system 
optional header is 36 bytes on the 3B20 computer, 28 bytes other- 
wise. The valid magic numbers are given below: 

#define N3BMAGIC 0550 /* 3B20 computer */ 
#define NTVMAGIC 0551 /* 3B20 computer */ 



#define VAXWRMAGIC 0570 /* writable text segments */ 
#define VAXROMAGIC 0575 /* readonly sharable segments */ 

The value in f timdat is obtained from the timed) system call. 
Flag bits currently defined are: 



#define F RELFLG 00001 

#define FJEXEC 00002 

#define F LNNO 00004 

#define F LSYMS 00010 

#define F MINMAL 00020 

#define F UPDATE 00040 

#define F SWABD 00100 

#define F AR16WR 00200 



/* relocation entries stripped */ 

/* file is executable */ 

/* line numbers stripped */ 

/* local symbols stripped */ 

/* minimal object file */ 

/* update file, ogen produced */ 

/* file is "pre-swabbed" */ 

/* 16 bit DEC host */ 
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#define F_AR32WR 00400 
#define F_AR32W 01000 
#define FPATCH 02000 

SEE ALSO 

time(2), fseek(3S), a.out(4). 



/* 32 bit DEC host */ 

/* non-DEC host */ 

/* "pa tch " l ist in °Pt hdr */ 
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NAME 

file system — format of system volume 

SYNOPSIS 

#include <sys/filsys.h> 
#include <sys/types.h> 
#include <sys/param.h> 

DESCRIPTION 

Every file system storage volume has a common format for certain 
vital information. Every such volume is divided into a certain 
number of 512-byte long sectors. Sector 0 is unused and is avail- 
able to contain a bootstrap program or other information. 

Sector 1 is the super -block. The format of a super-block is: 



/* 






* Structure of the super-block 
*/ 




struct filsys 
{ 






ushort 


sjsize; 


/* size in blocks of i-list •/ 


daddrt 


s_fsize; 


/* size in blocks of entire volume */ 


short 


sjifree; 


/* number of addresses in s free */ 


daddrj 


s_free[NICFREE]; 


/* free block list */ 


short 


sninode; 


/* number of i-nodes in s inode */ 


inot 


s_inode[NICINODj; 


/* free i-node list */ 


char 


sflock; 


/* lock during free list manipulation */ 


char 


silock; 


/* lock during i-list manipulation •/ 


char 


sfmod; 


/* super block modified flag */ 


char 


sronly; 


/» mounted read-only flag */ 


timet 


stime; 


/* last super block update */ 


short 


s_dinfo[4]; 


/* device information */ 


daddrt 


stfree; 


/* total free blocks*/ 


inot 


stinode; 


/* total free i-nodes */ 


char 


s_fnamel6]; 


/* file system name */ 


char 


s_fpack[6]; 


/* file system pack name */ 


long 


s_fill[13l; 


/* ADJUST to make sizeof filsys be 512 */ 


long 


smagic; 


/* magic # to denote new file system */ 


long 


sjype; 


/* type of new file system */ 



}; 
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#define FsMAGIC Oxfdl87e20 



/* s magic number */ 



#define Fslb 
#define Fs2b 



2 



/* 512 byte block ♦/ 
/* 1024 byte block */ 



Sjype indicates the file system type. Currently, two types of file 
systems are supported: the original 512-byte oriented and the new 
improved 1024-byte oriented. S magic is used to distinguish the 
original 512-byte oriented file systems from the newer file systems. 
If this field is not equal to the magic number, FsMAGIC, the type 
is assumed to be Fslb, otherwise the sjype field is used. In the 
following description, a block is then determined by the type. For 
the original 512-byte oriented file system, a block is 512 bytes. 
For the 1024-byte oriented file system, a block is 1024 bytes or 
two sectors. The operating system takes care of all conversions 
from logical block numbers to physical sector numbers. 

SJsize is the address of the first data block after the i-list; the i- 
list starts just after the super-block, namely in block 2; thus the i- 
list is sJsize—2 blocks long. S Jsize is the first block not poten- 
tially available for allocation to a file. These numbers are used by 
the system to check for bad block numbers; if an "impossible" 
block number is allocated from the free list or is freed, a diagnos- 
tic is written on the on-line console. Moreover, the free array is 
cleared, so as to prevent further allocation from a presumably cor- 
rupted free list. 

The free list for each volume is maintained as follows. The s Jree 
array contains, in s Jreell], s Jree[snfree—l], up to 49 
numbers of free blocks. S Jree[0] is the block number of the head 
of a chain of blocks constituting the free list. The first long in 
each free-chain block is the number (up to 50) of free-block 
numbers listed in the next 50 longs of this chain member. The 
first of these 50 blocks is the link to the next member of the chain. 
To allocate a block: decrement sjtfree, and the new block is 
s Jree[snfree]. If the new block number is 0, there are no blocks 
left, so give an error. If sjtfree became 0, read in the block 
named by the new block number, replace sjtfree by its first word, 
and copy the block numbers in the next 50 longs into the s Jree 
array. To free a block, check if sjtfree is 50; if so, copy sjtfree 
and the s Jree array into it, write it out, and set sjtfree to 0. In 
any event set s Jree[sjtfree] to the freed block's number and 
increment sjtfree. 
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Sjfree is the total free blocks available in the file system. 

Sjiinode is the number of free i-numbers in the sjnode array. 
To allocate an i-node: if sjiinode is greater than 0, decrement it 
and return s models ninode]. If it was 0, read the i-list and place 
the numbers of all free i-nodes (up to 100) into the sjnode array, 
then try again. To free an i-node, provided sjiinode is less than 
100, place its number into s models ninode] and increment 
sjiinode. If sjiinode is already 100, do not bother to enter the 
freed i-node into any table. This list of i-nodes is only to speed up 
the allocation process; the information as to whether the i-node is 
really free or not is maintained in the i-node itself. 

Sjinode is the total free i-nodes available in the file system. 

S Jlock and sjlock are flags maintained in the core copy of the 
file system while it is mounted and their values on disk are imma- 
terial. The value of s Jmod on disk is likewise immaterial; it is 
used as a flag to indicate that the super-block has changed and 
should be copied to the disk during the next periodic update of file 
system information. 

Sjonly is a read-only flag to indicate write-protection. 

Sjime is the last time the super-block of the file system was 
changed, and is the number of seconds that have elapsed since 
00:00 Jan. 1, 1970 (GMT). During a reboot, the sjime of the 
super-block for the root file system is used to set the system's idea 
of the time. 

S Jhame is the name of the file system and s Jpack is the name of 
the pack. 

I-numbers begin at 1, and the storage for i-nodes begins in block 
2. Also, i-nodes are 64 bytes long. I-node 1 is reserved for future 
use. I-node 2 is reserved for the root directory of the file system, 
but no other i-number has a built-in meaning. Each i-node 
represents one file. For the format of an i-node and its flags, see 
inode (4) . 

FILES 

/usr/include/sys/filsys .h 
/usr/include/sys/stat.h 

SEE ALSO 

inode (4). 

fsck(lM), fsdb(lM), mkfs(lM) in the UNIX Programmer's 
Manual —Volume 3: System Administration Facilities. 
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NAME 

fspec — format specification in text files 
DESCRIPTION 

It is sometimes convenient to maintain text files on the UNIX sys- 
tem with non-standard tabs, (i.e., tabs which are not set at every 
eighth column). Such files must generally be converted to a stan- 
dard format, frequently by replacing all tabs with the appropriate 
number of spaces, before they can be processed by UNIX system 
commands. A format specification occurring in the first line of a 
text file specifies how tabs are to be expanded in the remainder of 
the file. 

A format specification consists of a sequence of parameters 
separated by blanks and surrounded by the brackets <: and :>. 
Each parameter consists of a keyletter, possibly followed immedi- 
ately by a value. The following parameters are recognized: 

ttabs The t parameter specifies the tab settings for the file. 
The value of tabs must be one of the following: 

1. a list of column numbers separated by commas, 
indicating tabs set at the specified columns; 

2. a — followed immediately by an integer n, indi- 
cating tabs at intervals of n columns; 

3. a — followed by the name of a "canned" tab 
specification. 

Standard tabs are specified by t— 8, or equivalently, 
tl,9,17,25,etc. The canned tabs which are recognized 
are defined by the tabsil) command. 

ssize The s parameter specifies a maximum line size. The 
value of size must be an integer. Size checking is 
performed after tabs have been expanded, but before 
the margin is prepended. 

mmargin The m parameter specifies a number of spaces to be 
prepended to each line. The value of margin must be 
an integer. 

d The d parameter takes no value. Its presence indi- 

cates that the line containing the format specification 
is to be deleted from the converted file. 

e The e parameter takes no value. Its presence indi- 

cates that the current format is to prevail only until 
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another format specification is encountered in the file. 

Default values, which are assumed for parameters not supplied, are 
t — 8 and mO. If the s parameter is not specified, no size checking 
is performed. If the first line of a file does not contain a format 
specification, the above defaults are assumed for the entire file. 
The following is an example of a line containing a format 
specification: 

* <:t5,10,15 s72:> * 

If a format specification can be disguised as a comment, it is not 
necessary to code the d parameter. 

Several UNIX system commands correctly interpret the format 
specification for a file. Among them is gath (see send (10) which 
may be used to convert files to a standard format acceptable to 
other UNIX system commands. 

SEE ALSO 

ed(l), newform(l), send(lC), tabs(l) in the UNIX Programmer's 
Manual —Volume 1: Commands and Utilities. 
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NAME 

gettydefs — speed and terminal settings used by getty 
DESCRIPTION 

The /etc/gettydefs file contains information used by getty (1M) to 
set up the speed and terminal settings for a line. It supplies infor- 
mation on what the login prompt should look like. It also supplies 
the speed to try next if the user indicates the current speed is not 
correct by typing a <break> character. 

Each entry in /etc/gettydefs has the following format: 

label# initial-flags # final-flags # login-prompt #next- 
label 

Each entry is followed by a blank line. The various fields can con- 
tain quoted characters of the form \b, \n, \c, etc., as well as \nnn, 
where nnn is the octal value of the desired character. The various 
fields are: 

label This is the string against which getty tries to match 

its second argument. It is often the speed, such as 
1200, at which the terminal is supposed to run, but 
it need not be (see below) . 

initial-flags These flags are the initial ioctl(2) settings to which 
the terminal is to be set if a terminal type is not 
specified to getty. The flags that getty understands 
are the same as the ones listed in 
/usr/include/sys/termio.h (see termioij)). Nor- 
mally only the speed flag is required in the initial- 
flags. Getty automatically sets the terminal to raw 
input mode and takes care of most of the other 
flags. The initial -flag settings remain in effect until 
getty executes login (1). 

final -flags These flags take the same values as the initial -flags 
and are set just prior to getty executes login. The 
speed flag is again required. The composite flag 
SANE takes care of most of the other flags that 
need to be set so that the processor and terminal 
are communicating in a rational fashion. The other 
two commonly specified final-flags are TAB3, so 
that tabs are sent to the terminal as spaces, and 
HUPCL, so that the line is hung up on the final 
close. 
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login-prompt This entire field is printed as the login-prompt. 

Unlike the above fields where white space is ignored 
(a space, tab or new-line), they are included in the 
login-prompt field. 

next-label If this entry does not specify the desired speed, 
indicated by the user typing a <break> character, 
then getty will search for the entry with next-label 
as its label field and set up the terminal for those 
settings. Usually, a series of speeds are linked 
together in this fashion, into a closed set; For 
instance, 2400 linked to 1200, which in turn is 
linked to 300, which finally is linked to 2400. 

If getty is called without a second argument, then the first entry of 
/etc/gettydefs is used, thus making the first entry of /etc/gettydefs 
the default entry. It is also used if getty can not find the specified 
label. If /etc/gettydefs itself is missing, there is one entry built 
into the command which will bring up a terminal at 300 baud. 

It is strongly recommended that after making or modifying 
/etc/gettydefs, it be run through getty with the check option to be 
sure there are no errors. 

FILES 

/etc/gettydefs 

SEE ALSO 

ioctl(2). 

getty (1M), termio(7) in the UNIX Programmer's Manual— 
Volume 3: System Administration Facilities. 
login (1) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
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NAME 

gps — graphical primitive string, format of graphical files 
DESCRIPTION 

GPS is a format used to store graphical data. Several routines 
have been developed to edit and display GPS files on various dev- 
ices. Also, higher level graphics programs such as plot (in 
stat (1G)) and vtoc (in tocilG)) produce GPS format output files. 

A GPS is composed of five types of graphical data or primitives. 

GPS PRIMITIVES 

lines The lines primitive has a variable number of points 
from which zero or more connected line segments are 
produced. The first point given produces a move to 
that location. (A move is a relocation of the graphic 
cursor without drawing.) Successive points produce 
line segments from the previous point. Parameters are 
available to set color, weight, and style (see below). 

arc The arc primitive has a variable number of points to 

which a curve is fit. The first point produces a move to 
that point. If only two points are included, a line con- 
necting the points will result; if three points a circular 
arc through the points is drawn; and if more than 
three, lines connect the points. (In the future, a spline 
will be fit to the points if they number greater than 
three.) Parameters are available to set color, weight, 
and style. 

text The text primitive draws characters. It requires a sin- 

gle point which locates the center of the first character 
to be drawn. Parameters are color, font, textsize, and 
textangle. 

hardware The hardware primitive draws hardware characters or 
gives control commands to a hardware device. A single 
point locates the beginning location of the hardware 
string. 

comment A comment is an integer string that is included in a 
GPS file but causes nothing to be displayed. All GPS 
files begin with a comment of zero length. 

GPS PARAMETERS 

color Color is an integer value set for arc, lines, and text 
primitives. 
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Weight is an integer value set for arc and lines primi- 
tives to indicate line thickness. The value 0 is narrow 
weight, 1 is bold, and 2 is medium weight. 

Style is an integer value set for lines and arc primitives 
to give one of the five different line styles that can be 
drawn on TEKTRONIX 4010 series storage tubes. 
They are: 

0 solid 

1 dotted 

2 dot dashed 

3 dashed 

4 long dashed 

An integer value set for text primitives to designate the 
text font to be used in drawing a character string. 
(Currently font is expressed as a four-bit weight value 
followed by a four-bit style value.) 

Textsize is an integer value used in text primitives to 
express the size of the characters to be drawn. 
Textsize represents the height of characters in absolute 
universe-units and is stored at one-fifth this value in 
the size-orientation (so) word (see below). 

textangle Textangle is a signed integer value used in text primi- 
tives to express rotation of the character string around 
the beginning point. Textangle is expressed in degrees 
from the positive x-axis and can be a positive or nega- 
tive value. It is stored in the size-orientation (so) word 
as a value 256/360 of it's absolute value. 

ORGANIZATION 

GPS primitives are organized internally as follows: 



lines cw points sw 

arc cw points sw 

text cw point sw so [string] 

hardware cw point [string] 

comment cw [string] 

cw Cw is the control word and begins all primitives. It 



consists of four bits that contain a primitive-type code 
and twelve bits that contain the word-count for that 
primitive. 
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point (s) Point (s) is one or more pairs of integer coordinates. 

Text and hardware primitives only require a single 
point. Pointis) are values within a Cartesian plane or 
universe having 64K (— 32K to +32K) points on each 
axis. 

sw Sw is the style-word and is used in lines, arc, and text 

primitives. For all three, eight bits contain color infor- 
mation. In arc and lines eight bits are divided as four 
bits weight and four bits style. In the text primitive 
eight bits of sw contain the font. 

so So is the size-orientation word used in text primitives. 

Eight bits contain text size and eight bits contain text 
rotation. 

string String is a null-terminated character string. If the 
string does not end on a word boundary, an additional 
null is added to the GPS file to insure word-boundary 
alignment. 

SEE ALSO 

graphics (1G), stat(lG), toc(lG) in the UNIX Programmer's 
Manual —Volume I: Commands and Utilities. 
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NAME 

group — group file 

DESCRIPTION 

Group contains for each group the following information: 

group name 
encrypted password 
numerical group ID 

comma-separated list of all users allowed in the group 

This is an ASCII file. The fields are separated by colons; each 
group is separated from the next by a new-line. If the password 
field is null, no password is demanded. 

This file resides in directory /etc. Because of the encrypted pass- 
words, it can and does have general read permission and can be 
used, for example, to map numerical group ID's to names. 

FILES 

/etc/group 

SEE ALSO 

crypt (3 C), passwd(4). 

newgrp(l), passwd(l) in the UNIX Programmer's Manual— 
Volume 1: Commands and Utilities. 
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NAME 

inittab — script for the init process 
DESCRIPTION 

The inittab file supplies the script to inifs role as a general process 
dispatcher. The process that constitutes the majority of init's pro- 
cess dispatching activities is the line process /etc/getty that ini- 
tiates individual terminal lines. Other processes typically 
dispatched by init are daemons and the shell. 

The inittab file is composed of entries that are position dependent 
and have the following format: 

id:rstate:action:process 

Each entry is delimited by a newline, however, a backslash (\) 
preceding a newline indicates a continuation of the entry. Up to 
512 characters per entry are permitted. Comments may be 
inserted in the process field using the sh (1) convention for com- 
ments. Comments for lines that spawn gettys are displayed by the 
who (I) command. It is expected that they will contain some 
information about the line such as the location. There are no lim- 
its (other than maximum entry size) imposed on the number of 
entries within the inittab file. The entry fields are: 

id This is one or two characters used to uniquely identify an 

entry. 

r state This defines the run-level in which this entry is to be pro- 
cessed. Run-levels effectively correspond to a 
configuration of processes in the system. That is, each 
process spawned by init is assigned a run-level or run- 
levels in which it is allowed to exist. The run-levels are 
represented by a number ranging from 0 through 6. As 
an example, if the system is in run-level 1, only those 
entries having a 1 in the rstate field will be processed. 
When init is requested to change run-levels, all processes 
which do not have an entry in the rstate field for the tar- 
get run-level will be sent the warning signal (SIGTERM) 
and allowed a 20-second grace period before being forci- 
bly terminated by a kill signal (SIGKILL). The rstate 
field can define multiple run-levels for a process by 
selecting more than one run-level in any combination 
from 0—6. If no run-level is specified, then the process 
is assumed to be valid at all run-levels 0—6. There are 
three other values, a, b and c, which can appear in the 
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r state field, even though they are not true run-levels. 
Entries which have these characters in the rstate field are 
processed only when the telinit (see init (IM)) process 
requests them to be run (regardless of the current run- 
level of the system). They differ from run- levels in that 
init can never enter run-level a, b or c. Also, a request 
for the execution of any of these processes does not 
change the current run-level. Furthermore, a process 
started by an a, b or c command is not killed when init 
changes levels. They are only killed if their line in 
/etc/inittab is marked off in the action field, their line is 
deleted entirely from /etc/inittab, or init goes into the 
SINGLE USER state. 

action Key words in this field tell init how to treat the process 
specified in the process field. The actions recognized by 
init are as follows: 

respawn If the process does not exist then start the 
process, do not wait for its termination (con- 
tinue scanning the inittab file), and when it 
dies restart the process. If the process 
currently exists then do nothing and continue 
scanning the inittab file. 

wait Upon inifs entering the run-level that 

matches the entry's rstate, start the process 
and wait for its termination. All subsequent 
reads of the inittab file while init is in the 
same run-level will cause init to ignore this 
entry. 

once Upon inifs entering a run-level that matches 

the entry's rstate, start the process, do not 
wait for its termination. When it dies, do 
not restart the process. If upon entering a 
new run-level, where the process is still run- 
ning from a previous run-level change, the 
program will not be restarted. 

boot The entry is to be processed only at init's 

boot-time read of the inittab file. Init is to 
start the process, not wait for its termination; 
and when it dies, not restart the process. In 
order for this instruction to be meaningful, 
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the rstate should be the default or it must 
match iw7's run-level at boot time. This 
action is useful for an initialization function 
following a hardware reboot of the system. 

bootwait The entry is to be processed only at inifs 
boot-time read of the inittab file. Init is to 
start the process, wait for its termination 
and, when it dies, not restart the process. 

powerfail Execute the process associated with this 
entry only when init receives a power fail sig- 
nal (SIGPWR see signal (2)). 

powerwait Execute the process associated with this 
entry only when init receives a power fail sig- 
nal (SIGPWR) and wait until it terminates 
before continuing any processing of inittab. 

off If the process associated with this entry is 

currently running, send the warning signal 
(SIGTERM) and wait 20 seconds before forci- 
bly terminating the process via the kill signal 
(SIGKILL). If the process is nonexistent, 
ignore the entry. 

ondemand This instruction is really a synonym for the 
respawn action. It is functionally identical to 
respawn but is given a different keyword in 
order to divorce its association with run- 
levels. This is used only with the a, b or c 
values described in the rstate field. 

initdefault An entry with this action is only scanned 
when init initially invoked. Init uses this 
entry, if it exists, to determine which run- 
level to enter initially. It does this by taking 
the highest run-level specified in the rstate 
field and using that as its initial state. If the 
rstate field is empty, this is interpreted as 
0123456 and so init will enter run-level 6. 
Also, the initdefault entry cannot specify that 
init start in the SINGLE USER state. Addi- 
tionally, if init does not find an initdefault 
entry in /etc/inittab, then it will request an 
initial run-level from the user at reboot time. 
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sysinit 



Entries of this type are executed before init 
tries to access the console. It is expected 
that this entry will be only used to initialize 
devices on which init might try to ask the 
run-level question. These entries are exe- 
cuted and waited for before continuing. 



process This is a sh command to be executed. The entire process 
field is prefixed with exec and passed to a forked sh as sh 
— c 'exec command'. For this reason, any legal sh syntax 
can appear in the process field. Comments can be 
inserted with the ; #comment syntax. 

FILES 

/etc/inittab 

SEE ALSO 

exec (2), open (2), signal (2). 

getty(lM), init(lM) in the UNIX Programmer's Manual— Volume 
3: System Administration Facilities. 

sh(l), who(l) in the UNIX Programmer's Manual —Volume 1: 
Commands and Utilities. 
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NAME 

inode — format of an i-node 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ino.h> 

DESCRIPTION 

An i-node for a plain file or directory in a file system has the fol- 
lowing structure defined by <sys/ino.h>. 

/* Inode structure as it appears on a disk block. */ 
struct dinode 



{ 



}; 
/* 



ushort di mode; /* mode and type of file */ 

short di nlink; /* number of links to file */ 

ushort di uid; /* owner's user id */ 

ushort dijgid; /* owner's group id */ 

off t di size; /* number of bytes in file */ 

char di_addr[40]; /* disk block addresses */ 

time t di atime; /* time last accessed */ 

time_t dijntime; /* time last modified */ 

time t di_ctime; /* time of last file status change */ 



FILES 



* the 40 address bytes: 

* 39 used; 13 addresses 

* of 3 bytes each. 
*/ 

For the meaning of the defined types off J and time J see 
types (5). 

/usr/include/sys/ino.h 



SEE ALSO 

stat (2), fs (4), types (5). 
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NAME 

issue — issue identification file 
DESCRIPTION 

The file /etc/issue contains the issue or project identification to be 
printed as a login prompt. This is an ASCII file which is read by 
program getty and then written to any terminal spawned or 
respawned from the lines file. 

FILES 

/etc/issue 
SEE ALSO 

login(l) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
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NAME 

Idfcn — common object file access routines 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

DESCRIPTION 

The common object file access routines are a collection of func- 
tions for reading an object file that is in the 3B20 computer (com- 
mon) object file format. Although the calling program must know 
the detailed structure of the parts of the object file that it 
processes, the routines effectively insulate the calling program from 
knowledge of the overall structure of the object file. 

The interface between the calling program and the object file 
access routines is based on the defined type LDFILE, defined as 
struct Idfile, declared in the header file Idfcn.h. The primary pur- 
pose of this structure is to provide uniform access to both simple 
object files and to object files that are members of an archive file. 

The function ldopen(3X) allocates and initializes the LDFILE 
structure and returns a pointer to the structure to the calling pro- 
gram. The fields of the LDFELE structure may be accessed indivi- 
dually through macros defined in Idfcn.h and contain the following 
information: 

LDFILE *ldptr; 

TYPE(ldptr) The file magic number used to distinguish 
between archive members and simple object files. 

IOPTR(ldptr) The file pointer returned by /open and used by 
the standard input/output functions. 

OFFSET (ldptr) The file address of the beginning of the object 
file; the offset is non-zero if the object file is a 
member of an archive file. 

HEADER (ldptr) The file header structure of the object file. 

The object file access functions themselves may be divided into 
four categories: 

(1) functions that open or close an object file 
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ldopen(3X) and ldopen(3X) 

open a common object file 
ldclose(3X) and IdcloseOX) 

close a common object file 

(2) functions that read header or symbol table informa- 
tion 

ldahread(3X) 

read the archive header of a member of 

an archive file 
ldfhread(3X) 

read the file header of a common object 

file 

IdshreadOX) and ldshread(3X) 

read a section header of a common object 
file 

Idt bread (3X) 

read a symbol table entry of a common 

object file 
Idgetname (3X) 

retrieve a symbol name from a symbol 

table entry or from the string table 

(3) functions that position an object file at (seek to) the 
start of the section, relocation, or line number information 
for a particular section. 

ldohseek(3X) 

seek to the optional file header of a com- 
mon object file 

Idsseek (3X) and Idsseek (3X) 

seek to a section of a common object file 

ldrseek{3X) and ldrseek(3X) 

seek to the relocation information for a 
section of a common object file 

ldlseek(3X) and ldlseek(3X) 

seek to the line number information for a 
section of a common object file 

IdtbseekOX) 

seek to the symbol table of a common 
object file 

(4) the function ldtbindex{3X) which returns the index of 
a particular common object file symbol table entry. 
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These functions are described in detail on their respective manual 
pages. 

All the functions except ldopen(3X) , ldgetname(3X), ldopen(3X), 
and Idtbindex (3X) return either SUCCESS or FAILURE, both con- 
stants defined in ldfcn.h. Ldopen(3X) and ldopen{3X) both 
return pointers to an LDFILE structure. 

Additional access to an object file is provided through a set of 
macros defined in ldfcn.h. These macros parallel the standard 
input/output file reading and manipulating functions, translating a 
reference of the LDFILE structure into a reference to its file 
descriptor field. 

The following macros are provided: 

GETC(ldptr) 
FGETC(ldptr) 
GETW(ldptr) 
UNGETCCc, ldptr) 
FGETS(s, n, ldptr) 

FREAD((char *) ptr, sizeof (*ptr), nitems, ldptr) 

FSEEK (ldptr, offset, ptrname) 

FTELL (ldptr) 

REWIND (ldptr) 

FEOF(ldptr) 

FERROR (ldptr) 

FILENO (ldptr) 

SETBUF (ldptr, buf) 

STROFFSET (ldptr) 

The STROFFSET macro calculates the address of the string table 
in a UNIX system release 5.0 object file. See the manual entries 
for the corresponding standard input/output library functions for 
details on the use of the rest of the macros. 

The program must be loaded with the object file access routine 
library libld.a. 

WARNING 

The macro FSEEK defined in the header file ldfcn.h translates into 
a call to the standard input/output function / seek (3S). FSEEK 
should not be used to seek from the end of an archive file since the 
end of an archive file may not be the same as the end of one of its 
object file members! 
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SEE ALSO 

fseek(3S), ldahread(3X), ldclose(3X), ldgetname(3X), 
ldfhread (3X) , ldlread (3X) , ldlseek(3X) , ldohseek (3X) , 
ldopen(3X), ldrseek(3X), ldlseek(3X), ldshread(3X), 
ldtbindex(3X), ldtbread(3X), ldtbseek(3X), intro(5). 
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NAME 

linenum — line number entries in a common object file 

SYNOPSIS 

#include < linenum.h > 

DESCRIPTION 

Compilers based on pec generate an entry in the object file for 
each C source line on which a breakpoint is possible (when 
invoked with the — g option; see cc{\)). Users can then reference 
line numbers when using the appropriate software test system (see 
sdb(l)). The structure of these line number entries appears 
below. 

struct 
{ 



}; 

Numbering starts with one for each function. The initial line 
number entry for a function has IJnno equal to zero, and the sym- 
bol table index of the function's entry is in Isymndx. Otherwise, 
IJnno is non-zero, and / _paddr is the physical address of the code 
for the referenced line. Thus the overall structure is the following: 



laddr IJnno 

function symtab index 0 

physical address line 

physical address line 

function symtab index 0 

physical address line 

physical address line 



hneno 

union 
{ 

long I symndx ; 

long l_paddr ; 

} l_addr ; 

unsigned short IJnno ; 
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SEE ALSO 

a.out(4). 

cc(l), sdb(l) in the UNIX Programmer's Manual— Volume 1: 
Commands and Utilities. 
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NAME 

master — master device information table 
DESCRIPTION 

This file is used by the config (IM) program to obtain device infor- 
mation that enables it to generate the configuration files. The file 
consists of 3 parts, each separated by a line with a dollar sign ($) 
in column 1. Part 1 contains device information; part 2 contains 
names of devices that have aliases; part 3 contains tunable param- 
eter information. Any line with an asterisk (*) in column 1 is 
treated as a comment. 

Part 1 contains lines consisting of at least 10 fields and at most 13 
fields, with the fields delimited by tabs and/or blanks: 

Field 1 : device name (8 chars, maximum) . 

Field 2: interrupt vector size (decimal, in bytes) . 

Field 3: device mask (octal)— each "on" bit indicates 
that the handler exists: 

000100 initialization handler 
000040 power-failure handler 
000020 open handler 
000010 close handler 
000004 read handler 
000002 write handler 

000001 ioctl handler. 
Field 4: device type indicator (octal) : 

000400 VAX-1 1/780 massbus 
adapter 

000200 allow only one of these 
devices 

000100 suppress count field in the 
conf.c file 

000040 suppress interrupt vector 
000020 required device 
000010 block device 
000004 character device 

000002 floating vector 
000001 fixed vector. 

Field 5: handler prefix (4 chars, maximum). 
Field 6: device address size (decimal) . 
Field 7: major device number for block-type device. 
Field 8: major device number for character-type 
device. 
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Field 9: maximum number of devices per controller 
(decimal). 

Field 10: maximum bus request level (4 through 7). 
Fields 11-13: optional configuration table structure 
declarations (8 chars, maximum). 

Part 2 contains lines with 2 fields each: 

Field 1: alias name of device (8 chars, maximum). 
Field 2: reference name of device (8 chars, max- 
imum; specified in part 1). 

Part 3 contains lines with 2 or 3 fields each: 

parameter name (as it appears in descrip- 
tion file; 20 chars, maximum) 
parameter name (as it appears in the conf.c 
file; 20 chars, maximum) 
default parameter value (20 chars, max- 
imum; parameter specification is required if 
this field is omitted) 

Devices that are not interrupt-driven have an interrupt vector size 
of zero. The 040 bit in Field 4 causes config (1M) to record the 
interrupt vector although the low.s (univec.c on the VAX- 11/780) 
file will show no interrupt vector assignment at those locations 
(interrupts here will be treated as strays). 

SEE ALSO 

config (1M) in the UNIX Programmer's Manual —Volume 3: Sys- 
tem Administration Facilities. 



Field 1: 
Field 2: 
Field 3: 
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NAME 

mnttab — mounted file system table 

SYNOPSIS 

#include <mnttab.h> 

DESCRIPTION 

Mnttab resides in directory /etc and contains a table of devices, 
mounted by the mount (1M) command, in the following structure 
as defined by <mnttab.h>: 



Each entry is 70 bytes in length; the first 32 bytes are the null- 
padded name of the place where the special file is mounted; the 
next 32 bytes represent the null-padded root name of the mounted 
special file; the remaining 6 bytes contain the mounted special 
filers read/write permissions and the date on which it was 
mounted. 

The maximum number of entries in mnttab is based on the system 
parameter NMOUNT located in /usr/src/uts/cf/conf.c, which 
defines the number of allowable mounted special files. 

SEE ALSO 

mount(lM), setmnt(lM) in the UNIX Programmer's Manual— 
Volume 3: System Administration Facilities. 
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struct 



mnttab { 



char 
char 
short 
time t 



mt_dev[32]; 
mt_filsys[32]; 
mtroflg; 
mt_time; 



}; 
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NAME 

passwd — password file 

DESCRIPTION 

Passwd contains for each user the following information: 

login name 
encrypted password 
numerical user ID 
numerical group ID 

GCOS job number, box number, optional GCOS user ID 
initial working directory 
program to use as shell 

This is an ASCII file. Each field within each user's entry is 
separated from the next by a colon. The GCOS field is used only 
when communicating with that system, and in other installations 
can contain any desired information. Each user is separated from 
the next by a new-line. If the password field is null, no password 
is demanded; if the shell field is null, the shell itself is used. 

This file resides in directory /etc. Because of the encrypted pass- 
words, it can and does have general read permission and can be 
used, for example, to map numerical user IDs to names. 

The encrypted password consists of 13 characters chosen from a 
64-character alphabet (., /, 0-9, A-Z, a-z), except when the 
password is null, in which case the encrypted password is also null. 
Password aging is effected for a particular user if his encrypted 
password in the password file is followed by a comma and a non- 
null string of characters from the above alphabet. (Such a string 
must be introduced in the first instance by the super-user.) 

The first character of the age, AT say, denotes the maximum 
number of weeks for which a password is valid. A user who 
attempts to login after his password has expired will be forced to 
supply a new one. The next character, m say, denotes the 
minimum period in weeks which must expire before the password 
may be changed. The remaining characters define the week 
(counted from the beginning of 1970) when the password was last 
changed. (A null string is equivalent to zero.) M and m have 
numerical values in the range 0—63 that correspond to the 64- 
character alphabet shown above (i.e., / — 1 week; z = 63 weeks). 
If m — M — 0 (derived from the string . or ..) the user will be 
forced to change his password the next time he logs in (and the 
"age" will disappear from his entry in the password file) . If m > 
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M (signified, e.g., by the string ./) only the super-user will be able 
to change the password. 

FILES 

/etc/passwd 
SEE ALSO 

a641(3C), crypt(3C), getpwent(3C), group(4). 

login (1), passwd(l) in the UNIX Programmer's Manual —Volume 

1: Commands and Utilities. 
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NAME 

plot — graphics interface 
DESCRIPTION 

Files of this format are produced by routines described in 
plot(3X) and are interpreted for various devices by commands 
described in tplot (1G). A graphics file is a stream of plotting 
instructions. Each instruction consists of an ASCII letter usually 
followed by bytes of binary information. The instructions are exe- 
cuted in order. A point is designated by four bytes representing 
the x and y values; each value is a signed integer. The last desig- 
nated point in an 1, m, n, or p instruction becomes the "current 
point" for the next instruction. 

Each of the following descriptions begins with the name of the 
corresponding routine in plot(3X). 

m move: The next four bytes give a new current point. 

n cont: Draw a line from the current point to the point given by 
the next four bytes. See tplot (IG). 

p point: Plot the point given by the next four bytes. 

1 line: Draw a line from the point given by the next four bytes 
to the point given by the following four bytes. 

t label: Place the following ASCII string so that its first charac- 
ter falls on the current point. The string is terminated by a 
new-line. 

e erase: Start another frame of output. 

f linemod: Take the following string, up to a new-line, as the 
style for drawing further lines. The styles are "dotted", 
"solid", "longdashed", "shortdashed", and "dotdashed". 
Effective only for the — T4014 and -Tver options of tplot (1G) 
(TEKTRONIX 4014 terminal and Versatec plotter). 

s space: The next four bytes give the lower left corner of the 
plotting area; the following four give the upper right corner. 
The plot will be magnified or reduced to fit the device as 
closely as possible. 

Space settings that exactly fill the plotting area with unity scaling 
appear below for devices supported by the filters of tplot (1G). 
The upper limit is just outside the plotting area. In every case the 
plotting area is taken to be square; points outside may be display- 
able on devices whose face is not square. 
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DASI 300 space(0, 0, 4096, 4096); 

DASI 300s space(0, 0, 4096, 4096); 

DASI 450 space(0, 0, 4096, 4096); 

TEKTRONIX 4014 space (0, 0, 3120, 3120); 

Versatec plotter space (0, 0, 2048, 2048); 

SEE ALSO 

plot(3X), gps(4), term(5). 

graph (1G), tplot(lG) in the UNIX Programmer's Manual — 
Volume 1: Commands and Utilities. 

WARNING 

The plotting library plot(3X) and the curses library curses (3X) 
both use the names erase 0 and moveO. The curses versions are 
macros. If you need both libraries, put the plotiyX) code in a 
different source file than the curses (3X) code, and/or #undef 
moveO and erase () in the plot(3X) code. 
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NAME 

pnch — file format for card images 
DESCRIPTION 

The PNCH format is a convenient representation for files consist- 
ing of card images in an arbitrary code. 

A PNCH file is a simple concatenation of card records. A card 
record consists of a single control byte followed by a variable 
number of data bytes. The control byte specifies the number 
(which must lie in the range 0-80) of data bytes that follow. The 
data bytes are 8 -bit codes that constitute the card image. If there 
are fewer than 80 data bytes, it is understood that the remainder 
of the card image consists of trailing blanks. 

SEE ALSO 

send(lC) in the UNIX Programmer s Manual— Volume 1: Com- 
mands and Utilities. 
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NAME 

profile — setting up an environment at login time 
DESCRIPTION 

If your login directory contains a file named .profile, that file will 
be executed (via exec .profile) before your session begins; .profiles 
are handy for setting exported environment variables and terminal 
modes. If the file /etc/profile exists, it will be executed for every 
user before the .profile. The following example is typical (except 
for the comments) : 

# Make some environment variables global 
export MAIL PATH TERM 

# Set file creation mask 
umask 22 

# Tell me when new mail comes in 
M AIL=/ usr/ mail/myname 

# Add my /bin directory to the shell search sequence 
PATH=$PATH:$HOME/bin 

# Set terminal type 
echo "terminal: \c" 
read TERM 

case $TERM in 



300) 


stty cr2 nlO tabs; tabs;; 


300s) 


stty cr2 nlO tabs; tabs;; 


450) 


stty cr2 nlO tabs; tabs;; 


hp) 


stty crO nlO tabs; tabs;; 


745 | 735) 


stty crl nil -tabs; TERM=745;; 


43) 


stty crl nlO —tabs;; 


4014 | tek) 


stty crO nlO -tabs ffl; TERM=4014; echo "\33;";; 


*) 


echo "STERM unknown";; 



esac 

FILES 

SHOME/.profile 
/etc/profile 

SEE ALSO 

environ (5), term (5). 

env(l), login(l), mail(l), sh(l), stty(l), su(l) in the UNIX 
Programmer's Manual —Volume 1: Commands and Utilities. 
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NAME 

reloe — relocation information for a common object file 

SYNOPSIS 

#include <reloc.h> 

DESCRIPTION 

Object files have one relocation entry for each relocatable refer- 
ence in the text or data. If relocation information is present, it 
will be in the following format. 

struct reloc 
{ 

long rvaddr ; /* (virtual) address of reference */ 

long r symndx ; /* index into symbol table */ 

short r_tyP e ; /* relocation type */ 

}; 



/* 

* All generics 

* reloc. already performed to symbol in the same section 
*/ 

#define R ABS 0 
/* 

* 3B computer generic 

* 24-bit direct reference 

* 24-bit "relative" reference 

* 16-bit optimized "indirect" TV reference 

* 24-bit "indirect" TV reference 

* 32-bit "indirect" TV reference 
*/ 

#define R_DIR24 04 
#define R REL24 05 
#define R_OPT16 014 
#define RJND24 015 
#define R IND32 016 

/* 

* On most processors 
*/ 

#define R RELBYTE 017 
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#define RRELWORD 020 

#define R RELLONG 021 

#define RPCRBYTE 022 

#define R_PCRWORD 023 

#define R PCRLONG 024 



As the link editor reads each input section and performs reloca- 
tion, the relocation entries are read. They direct how references 
found within the input section are treated. 

R_ABS The reference is absolute, and no relocation is neces- 

sary. The entry will be ignored. 

R_DIR24 A direct, 24-bit reference to a symbol's virtual 
address. 

R REL24 A "PC-relative", 24-bit reference to a symbol's vir- 
tual address. Relative references occur in instruc- 
tions such as jumps and calls. The actual address 
used is obtained by adding a constant to the value of 
the program counter at the time the instruction is 
executed. 

R_OPT16 An optimized, indirect, 16-bit reference through a 
transfer vector. The instruction contains the offset 
into the transfer vector table to the transfer vector 
where the actual address of the referenced word is 
stored. 

RIND24 An indirect, 24-bit reference through a transfer vec- 
tor. The instruction contains the virtual address of 
the transfer vector, where the actual address of the 
referenced word is stored. 

R_IND32 An indirect, 32-bit reference through a transfer vec- 
tor. The instruction contains the virtual address of 
the transfer vector, where the actual address of the 
referenced word is stored. 

R RELBYTE A direct 8-bit reference to a symbol's virtual 
address. 



R RELWORD 



A direct 16-bit reference to a symbol's virtual 
address. 
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RRELLONG 

A direct 32-bit reference to a symbol's virtual 
address. 

RPCRBYTE A "PC-relative", 8-bit reference to a symbol's virtual 
address. 

R_PCRWORD 

A "PC-relative", 16-bit reference to a symbol's vir- 
tual address. 

R_PCRLONG 

A "PC-relative", 32-bit reference to a symbol's vir- 
tual address. 

On most processors relocation of a symbol index of -1 indicates 
that the relative difference between the current segment's start 
address and the program's load address is added to the relocatable 
address. 

Other relocation types will be defined as they are needed. 

Relocation entries are generated automatically by the assembler 
and automatically utilized by the link editor. A link editor option 
exists for removing the relocation entries from an object file. 

SEE ALSO 

a. out (4), syms(4). 

Id ( 1 ) , strip(l) in the UNIX Programmer's Manual —Volume 1: 
Commands and Utilities. 
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NAME 

sccsfile — format of SCCS file 
DESCRIPTION 

An file is an ASCII file. It consists of six logical parts: the check- 
sum, the delta table (contains information about each delta), 
user names (contains login names and/or numerical group IDs of 
users who may add deltas), flags (contains definitions of internal 
keywords), comments (contains arbitrary descriptive information 
about the file), and the body (contains the actual text lines inter- 
mixed with control lines). 

Throughout an file there are lines which begin with the ASCII 
SOH (start of heading) character (octal 001). This character is 
hereafter referred to as the control character and will be 
represented graphically as @. Any line described below which is 
not depicted as beginning with the control character is prevented 
from beginning with the control character. 

Entries of the form 

represent a five-digit string (a number between 00000 and 99999) . 
Each logical part of an file is described in detail below. 
Checksum 

The checksum is the first line of an file. The form of the 
line is: 

@h 

The value of the checksum is the sum of all characters, 
except those of the first line. The @h provides a magic 
number of (octal) 064001. 

Delta table 

The delta table consists of a variable number of entries of 
the form: 

@s // 

@d <type> <SCCSID> yr/mo/da hr:mi:se <pgmr> 
@i ... 
@x ... 
@g ... 

@m < number > 
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@c < comments > ... 



@e 

The first line (@s) contains the number of lines 
inserted/deleted/unchanged, respectively. The second line 
(@d) contains the type of the delta (currently, normal: D, 
and removed: R), the ID of the delta, the date and time of 
creation of the delta, the login name corresponding to the 
real user ID at the time the delta was created, and the 
serial numbers of the delta and its predecessor, respec- 
tively. 

The @i, @x, and @g lines contain the serial numbers of 
deltas included, excluded, and ignored, respectively. These 
lines are optional. 

The @m lines (optional) each contain one number associ- 
ated with the delta; the @c lines contain comments associ- 
ated with the delta. 

The @e line ends the delta table entry. 
User names 

The list of login names and/or numerical group IDs of 
users who may add deltas to the file, separated by new- 
lines. The lines containing these login names and/or 
numerical group IDs are surrounded by the bracketing 
lines @u and @U. An empty list allows anyone to make a 
delta. Any line starting with a ! prohibits the succeeding 
group or user from making deltas. 

Flags 

Keywords used internally (see admin (I) for more infor- 
mation on their use). Each flag line takes the form: 

@f <flag> < optional text> 

The following flags are defined: 

@f t <type of program> 
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@f v < program name> 

@f i < keyword string > 
@f b 

@f m < module name> 

@f f < floor > 

@f c < ceiling > 

@f d <default-sid> 
@f n 
@f j 

@ f 1 < lock-releases > 

@f q <user defined > 

@f z < reserved for use in interfaces > 



The t flag defines the replacement for the %Y% 
identification keyword. The v flag controls prompting for 
numbers in addition to comments; if the optional text is 
present it defines an number validity checking program. 
The i flag controls the warning/error aspect of the "No id 
keywords" message. When the i flag is not present, this 
message is only a warning; when the i flag is present, this 
message will cause a "fatal" error (the file will not be got- 
ten, or the delta will not be made). When the b flag is 
present the —b keyletter may be used on the get com- 
mand to cause a branch in the delta tree. The m flag 
defines the first choice for the replacement text of the 
%M% identification keyword. The f flag defines the 
"floor" release; the release below which no deltas may be 
added. The c flag defines the "ceiling" release; the release 
above which no deltas may be added. The d flag defines 
the default to be used when none is specified on a get 
command. The n flag causes delta to insert a "null" delta 
(a delta that applies no changes) in those releases that are 
skipped when a delta is made in a new release (e.g., when 
delta 5.1 is made after delta 2.7, releases 3 and 4 are 
skipped). The absence of the n flag causes skipped 
releases to be completely empty. The j flag causes get to 
allow concurrent edits of the same base . The 1 flag 
defines a list of releases that are locked against editing 
(get (l) with the — e keyletter). The q flag defines the 
replacement for the %Q% identification keyword. The z 
flag is used in certain specialized interface programs. 
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Comments 

Arbitrary text is surrounded by the bracketing lines @t 
and @T. The comments section typically will contain a 
description of the file's purpose. 

Body 

The body consists of text lines and control lines. Text 
lines do not begin with the control character, control lines 
do. There are three kinds of control lines: insert, "delete, 
and end, represented by: 

@I 
@D 

@E 



respectively. The digit string is the serial number 
corresponding to the delta for the control line. 

SEE ALSO 

admin (1), delta (1), get(l), prs(l) in the UNIX Programmer's 
Manual— Volume 1: Commands and Utilities. 
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NAME 

scnhdr — section header for a common object file 

SYNOPSIS 

#include < scnhdr .h > 

DESCRIPTION 

Every common object file has a table of section headers to specify 
the layout of the data within the file. Each section within an 
object file has its own header. The C structure appears below. 

struct scnhdr 



{ 



} 



char s_name[SYMNMLENl; /* section name */ 

long s_paddr; /* physical address */ 

long s vaddr; /* virtual address */ 

long s size; /* section size */ 

long sscnptr; /* file ptr to raw data */ 

long s relptr; /* file ptr to relocation */ 

long s lnnoptr; /* file ptr to line numbers */ 

unsigned short snreloc; /* # reloc entries */ 

unsigned short sjilnno; /* # line number entries */ 

long s_flags; /* flags */ 



File pointers are byte offsets into the file; they can be used as the 
offset in a call to fseek (3S). If a section is initialized, the file con- 
tains the actual bytes. An uninitialized section is somewhat 
different. It has a size, symbols defined in it, and symbols that 
refer to it. But it can have no relocation entries, line numbers, or 
data. Consequently, an uninitialized section has no raw data in 
the object file, and the values for s scnptr, s_relptr, s lnnoptr, 
s nreloc, and sjilnno are zero. 

SEE ALSO 

fseekOS), a.out(4). 

ld(l) in the UNIX Programmer's Manual— Volume 1: Commands 
and Utilities. 
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NAME 

syms — common object file symbol table format 

SYNOPSIS 

#include <syms.h> 

DESCRIPTION 

Common object files contain information to support symbolic 
software testing (see sdbil)). Line number entries, UnenumiA), 
and extensive symbolic information permit testing at the C source 
level. Every object file's symbol table is organized as shown below. 

File name 1. 

Function 1. 

Local symbols for function 1 . 
Function 2. 

Local symbols for function 2. 

Static externs for file 1. 



File name 2. 

Function 1. 

Local symbols for function 1 . 
Function 2. 

Local symbols for function 2. 

Static externs for file 2. 



Defined global symbols. 
Undefined global symbols. 

The entry for a symbol is a fixed-length structure. The members 
of the structure hold the name (null padded), its value, and other 
information. The C structure is given below. 
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#define SYMNMLEN 8 
#define FILNMLEN 14 



struct syment 
{ 

union 
{ 

char 

struct 

{ 

long 
long 

} _n_n; 

char 

}_n; 
long 
short 

unsigned short 

char 

char 

}; 



/* all ways to get symbol name */ 
_n_name[SYMNMLEN]; /* symbol name */ 



nzeroes; /* == OL when in string table */ 

n offset; /* location of name in table */ 

*_n_nptr[2]; /* allows overlaying */ 

n value; /* value of symbol */ 

n scnum; /* section number */ 

ntype; /* type and derived type */ 

n sclass; /* storage class */ 

njnumaux; /* number of aux entries */ 



#define njiame 
#define n zeroes 
#define n offset n.nn.noffset 
#define nnptr _n._n_nptr[ 1 ] 

Meaningful values and explanations for them are given in both 
syms.h and Common Object File Format. Anyone who needs to 
interpret the entries should seek more information in these sources. 
Some symbols require more information than a single entry; they 
are followed by auxiliary entries that are the same size as a sym- 
bol entry. The format follows. 



n._n_name 

n. n n. n zeroes 
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union auxent 
{ 

struct 
{ 



long 

union 

{ 



struct 
{ 



xtagndx; 



unsigned short x lnno; 
unsigned short x_size; 



} x lnsz; 

long xfsize; 



} x misc; 

union 

{ 



struct 
{ 



} 

struct 
{ 



long 
long 
x_fcn; 



xlnnoptr; 
x_endndx; 



} 



} 



unsigned short x dimenlDIMNUM]; 

x_ary; 

xfcnary; 



unsigned short x tvndx; 
} x_sym; 
struct 
{ 

char xfnamel FILNMLEN ] ; 
} x_file; 
struct 
{ 

long xscnlen; 
unsigned short x nreloc; 
unsigned short x nlinno; 
} xscn; 

struct 
{ 

long xtvfill; 
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} 



unsigned short xtvlen; 
unsigned short x_tvran[2]; 
xtv; 



}; 



Indexes of symbol table entries begin at zero. 

SEE ALSO 

a.out(4), linenum(4). 

sdb(l) in the UNIX Programmer's Manual— Volume 1: Com- 
mands and Utilities. 

CAVEATS 

On machines in which longs are equivalent to ints (3B20 com- 
puter), they are converted to ints in the compiler to minimize the 
complexity of the compiler code generator. Thus the information 
about which symbols are declared as longs and which, as ints, does 
not show up in the symbol table. 



UNIX Programmer's Manual System Calls and Library Routines— 393 



TERM (4) 



TERM (4) 



NAME 

term — format of compiled term file. 

SYNOPSIS 
term 

DESCRIPTION 

Compiled terminfo descriptions are placed under the directory 
/usr/lib/terminfo. In order to avoid a linear search of a huge 
UNIX system directory, a two-level scheme is used: 
/usr/lib/terminfo/c/name where name is the name of the terminal, 
and c is the first character of name. Thus, act4 can be found in 
the file /usr/lib/terminfo/a/act4. Synonyms for the same terminal 
are implemented by multiple links to the same compiled file. 

The format has been chosen so that it will be the same on all 
hardware. An 8 or more bit byte is assumed, but no assumptions 
about byte ordering or sign extension are made. 

The compiled file is created with the compile program, and read 
by the routine setupterm. Both of these pieces of software are 
part of curses (3X) . The file is divided into six parts: the header, 
terminal names, boolean flags, numbers, strings, and string table. 

The header section begins the file. This section contains six short 
integers in the format described below. These integers are (1) the 
magic number (octal 0432); (2) the size, in bytes, of the names 
section; (3) the number of bytes in the boolean section; (4) the 
number of short integers in the numbers section; (5) the number of 
offsets (short integers) in the strings section; (6) the size, in bytes, 
of the string table. 

Short integers are stored in two 8-bit bytes. The first byte con- 
tains the least significant 8 bits of the value, and the second byte 
contains the most significant 8 bits. (Thus, the value represented 
is 256*second+first.) The value —1 is represented by 0377, 0377, 
other negative value are illegal. The —1 generally means that a 
capability is missing from this terminal. Machines where this does 
not correspond to the hardware read the integers as two bytes and 
compute the result. 

The terminal names section comes next. It contains the first line 
of the terminfo description, listing the various names for the termi- 
nal, separated by the T character. The section is terminated with 
an ASCII NUL character. 
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The boolean flags have one byte for each flag. This byte is either 
0 or 1 as the flag is present or absent. The capabilities are in the 
same order as the file <term.h>. 

Between the boolean section and the number section, a null byte 
will be inserted, if necessary, to ensure that the number section 
begins on an even byte. All short integers are aligned on a short 
word boundary. 

The numbers section is similar to the flags section. Each capabil- 
ity takes up two bytes, and is stored as a short integer. If the 
value represented is —1, the capability is taken to be missing. 

The strings section is also similar. Each capability is stored as a 
short integer, in the format above. A value of —1 means the capa- 
bility is missing. Otherwise, the value is taken as an offset from 
the beginning of the string table. Special characters in "X or \c 
notation are stored in their interpreted form, not the printing 
representation. Padding information $<nn> and parameter infor- 
mation %x are stored intact in uninterpreted form. 

The final section is the string table. It contains all the values of 
string capabilities referenced in the string section. Each string is 
null terminated. 

Note that it is possible for setupterm to expect a different set of 
capabilities than are actually present in the file. Either the data- 
base may have been updated since setupterm has been recompiled 
(resulting in extra unrecognized entries in the file) or the program 
may have been recompiled more recently than the database was 
updated (resulting in missing entries). The routine setupterm 
must be prepared for both possibilities — this is why the numbers 
and sizes are included. Also, new capabilities must always be 
added at the end of the lists of boolean, number, and string capa- 
bilities. 

As an example, an octal dump of the description for the Micro- 
term ACT 4 is included: 

microterm|act4|microterm act iv, 

cr=*M, cudl='J, ind=M, bel=~G, am, cubl=*H, 
ed=~_, el=~, clear=% cup='T%pl%c%p2%c, 
cols#80, lines#24, cufl=~X, cuul="Z, home 588 *], 
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000 032 001 \0 025 \0 \b \0 212 \0 " \0 m i c r 

020 oterm|act4|micro 

040 t e r m act i v \0 \0 001 \0 \0 

060 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 

100 \0 \0 P \0 377 377 030 \0 377 377 377 377 377 377 377 377 

120 377 377 377 377 \0 \0 002 \0 377 377 377 377 004 \0 006 \0 

140 \b \0 377 377 377 377 \n \0 026 \0 030 \0 377 377 032 \0 

160 377 377 377 377 034 \0 377 377 036 \0 377 377 377 377 377 377 

200 377 377 377 377 377 377 377 377 377 377 377 377 377 377 377 377 

* 

520 377 377 377 377 \0 377 377 377 377 377 377 377 377 377 377 
540 377 377 377 377 377 377 007 \0 \r \0 \f \0 036 \0 037 \0 
560 024 % p 1 % c % p 2 % c \0 \n \0 035 \0 
600 \b \0 030 \0 032 \0 \n \0 

Some limitations: total compiled entries cannot exceed 4096 bytes. 
The name field cannot exceed 128 bytes. 

FILES 

/usr/lib/terminfo/*/* compiled terminal capability data base 

SEE ALSO 

curses (3X) , terminfo (4) . 
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NAME 

terminfo — terminal capability data base 

SYNOPSIS 

/usr/lib/terminfo/*/* 

DESCRIPTION 

Terminfo is a data base describing terminals, used, e.g.,, by vi(l) 
and curses (3X) . Terminals are described in terminfo by giving a 
set of capabilities which they have, and by describing how opera- 
tions are performed. Padding requirements and initialization 
sequences are included in terminfo. 

Entries in terminfo consist of a number of ',' separated fields. 
White space after each *,' is ignored. The first entry for each ter- 
minal gives the names which are known for the terminal, separated 
by 1' characters. The first name given is the most common abbre- 
viation for the terminal, the last name given should be a long name 
fully identifying the terminal, and all others are understood as 
synonyms for the terminal name. All names but the last should be 
in lower case and contain no blanks; the last name may well con- 
tain upper case and blanks for readability. 

Terminal names (except for the last, verbose entry) should be 
chosen using the following conventions. The particular piece of 
hardware making up the terminal should have a root name chosen, 
thus "hp2621". This name should not contain hyphens, except 
that synonyms may be chosen that do not conflict with other 
names. Modes that the hardware can be in, or user preferences, 
should be indicated by appending a hyphen and an indicator of the 
mode. Thus, a vtlOO in 132 column mode would be vtlOO-w. The 
following suffixes should be used where possible: 



Suffix 


Meaning 


Example 


-w 


Wide mode (more than 80 columns) 


vtlOO-w 


-am 


With auto, margins (usually default) 


vtlOO-am 


-nam 


Without automatic margins 


vtlOO-nam 


-n 


Number of lines on the screen 


aaa-60 


-na 


No arrow keys (leave them in local) 


clOO-na 


-«p 


Number of pages of memory 


cl00-4p 


-rv 


Reverse video 


clOO-rv 



CAPABILITIES 

The variable is the name by which the programmer (at the ter- 
minfo level) accesses the capability. The capname is the short 
name used in the text of the database, and is used by a person 
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updating the database. The i.code is the two letter internal code 
used in the compiled database, and always corresponds to the old 
termcap capability name. 

Capability names have no hard length limit, but an informal limit 
of 5 characters has been adopted to keep them short and to allow 
the tabs in the source file caps to line up nicely. Whenever possi- 
ble, names are chosen to be the same as or similar to the ANSI 
X3.64-1979 standard. Semantics are also intended to match those 
of the specification. 

(P) indicates that padding may be specified 

(G) indicates that the string is passed through tparm with 
parms as given (#0. 

(*) indicates that padding may be based on the number of 
lines affected 

(#.) indicates the ft 1 parameter. 



Variable 


Cap- 


I. 


Description 


Booleans 


name 


Code 




autoleftjmargin, 


bw 


bw 


cubl wraps from column 0 to last column 


auto_right_margin, 


am 


am 


Terminal has automatic margins 


beehivejglitch, 


xsb 


xb 


Beehive (fl— escape, f2— Ctrl C) 


ceol_standout_glitch, 


xhp 


xs 


Standout not erased by overwriting (hp) 


eatnewlinejglitch, 


xenl 


xn 


newline ignored after 80 cols (Concept) 


eraseoverstrike, 


eo 


eo 


Can erase overstrikes with a blank 


generictype, 


gn 


gn 


Generic line type (e.g.,, dialup, switch). 


hardcopy, 


he 


he 


Hardcopy terminal 


hasmetakey, 


km 


km 


Has a meta key (shift, sets parity bit) 


hasstatusline, 


hs 


hs 


Has extra "status line" 


insert_null_glitch, 


in 


in 


Insert mode distinguishes nulls 


memoryabove, 


da 


da 


Display may be retained above the screen 


memory below, 


db 


db 


Display may be retained below the screen 


movejnsertmode, 


mir 


mi 


Safe to move while in insert mode 


move_standout_mode, 


msgr 


ms 


Safe to move in standout modes 


overstrike, 


OS 


OS 


Terminal overstrikes 


statusjineescok, 


eslok 


es 


Escape can be used on the status line 


telerayj»litch, 


xt 


xt 


Tabs ruin, magic so char (Teleray 1061) 


tilde_glitch, 


hz 


hz 


Hazeltine; can not print "'s 


transparentunderline, 


ul 


ul 


underline character overstrikes 
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xon xoff, 


xon 


xo 


Numbers? 






columns, 


cols 


CO 


inittabs, 


it 


it 


lines, 


lines 


li 


lines of memory, 


1m 


lm 


magic cookiejglitch, 


xmc 


SB 


padding baud rate, 


ob 


ob 


virtual terminal, 


Vt 


Vt 


wiHtVt ctntiic lirif* 






Strings: 






back tab 


cbt 


bt 


bell, 


bel 


bl 


carriage return, 






change scroll region, 


csr 


cs 


clear all tabs 


tbc 


ct 


clear screen 


clear 


cl 




el 




clr eos 


ed 


cd 


column address, 


hpa 


ch 


command character 


emdeh 


CC 


cursor address 


cup 




cursor down 


cudl 


do 


cursor home, 


home 


ho 


cursor invisible 






uuiaui icii, 


cubl 


le 


c*tt renr mem n HHr**«« 

VUI 9UI lllvlll aUUlG99) 


1111 VU 


CM 


cursor normal, 


CI1UI 111 




cursor right, 


cufl 


nd 


cursor to 11 


11 


11 


cursor up, 




up 


cursorvisible, 


cwis 


vs 


deletejcharacter, 


dchl 


dc 


deleteline, 


dll 


dl 


disstatusline, 


dsl 


ds 


downhalfline, 


hd 


hd 


enteraltcharsetmode, 


smacs 


as 


enter_blink_mode, 


blink 


mb 



Terminal uses xon/xoff handshaking 

Number of columns in a line 
Tabs initially every # spaces 
Number of lines on screen or page 
Lines of memory if > lines. 0 means varies 
Number of blank chars left by smso or rmso 
Lowest baud where cr/nl padding is needed 
Virtual terminal number (UNIX system) 
No. columns in status line 

Back tab (P) 

Audible signal (bell) (P) 

Carriage return (P*) 

change to lines #1 through #2 (vtlOO) (PG) 

Clear all tab stops (P) 

Clear screen and home cursor (P*) 

Clear to end of line (P) 

Clear to end of display (P*) 

Set cursor column (PG) 

Term, settable cmd char in prototype 

Screen rel. cursor motion row #1 col #2 (PG) 

Down one line 

Home cursor (if no cup) 

Make cursor invisible 

Move cursor left one space 

Memory relative cursor addressing 

Make cursor appear normal (undo vs/vi) 

Non-destructive space (cursor right) 

Last line, first column (if no cup) 

Upline (cursor up) 

Make cursor very visible 

Delete character (P*) 

Delete line (P*) 

Disable status line 

Half-line down (forward 1/2 linefeed) 
Start alternate character set (P) 
Turn on blinking 
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enter_bold mode, 


bold 


md 


Turn on bold (extra bright) mode 


enter ca mode, 


smcup 


ti 


String to begin programs that use cup 


enterjdelete mode, 


smdc 


dm 


Delete mode (enter) 


enter dim mode, 


dim 


mh 


Turn on half-bright mode 


enter insert mode, 


smir 


im 


Insert mode (enter); 


enter_protected mode, 


prot 


mp 


Turn on protected mode 


enter_reverse_mode, 


rev 


mr 


Turn on reverse video mode 


enter secure mode, 


invis 


mk 


Turn on blank mode (chars invisible) 


enter standout mode, 


smso 


so 


Begin stand out mode 


enter underline mode, 


smul 


us 


Start underscore mode 


erase chars 


ech 


ec 


Erase #1 characters (PG) 


exit alt charset mode, 


rmacs 


ae 


End alternate character set (P) 


exit_attribute_mode, 


sgrO 


me 


Turn off all attributes 


exitjca mode, 


rmcup 


te 


String to end programs that use cup 


exitdeletemode, 


rmdc 


ed 


End delete mode 


exit_insert_mode, 


rmir 


ei 


End insert mode 


exitjstandoutjtnode, 


rmso 


se 


End stand out mode 


exitunderlinemode, 


rmul 


ue 


End underscore mode 


flash screen, 


flash 


vb 


Visible bell (may not move cursor) 


form_feed, 


ff 


ff 


Hardcopy terminal page eject (P*) 


from_status_line, 


fsl 


fs 


Return from status line 


init_l string, 


isl 


il 


Terminal initialization string 


init_2string, 


is2 


i2 


Terminal initialization string 


init_3string, 


is3 


i3 


Terminal initialization string 


initfile, 


if 


if 


Name of file containing is 


insert character, 


ichl 


ic 


Insert character (P) 


insert_line, 


ill 


al 


Add new blank line (P*) 


insert_padding, 


ip 


ip 


Insert pad after character inserted (P*) 


key backspace, 


kbs 


kb 


Sent by backspace key 


key catab, 


ktbc 


ka 


Sent by clear-all-tabs key 


key_clear, 


kclr 


kC 


Sent by clear screen or erase key 


keyctab, 


kctab 


kt 


Sent by clear-tab key 


key dc, 


kdchl 


IcD 


Sent by delete character key 


key_dl, 


kdll 


kL 


Sent by delete line key 


keydown, 


kcudl 


kd 


Sent by terminal down arrow key 


keyjeic, 


krmir 


kM 


Sent by rmir or smir in insert mode 


keyeol, 


kel 


kE 


Sent by clear-to-end-of-line key 


keyeos, 


ked 


kS 


Sent by clear-to-end-of-screen key 


key_fO, 


kfO 


kO 


Sent by function key fO 


key_fl, 


kfl 


kl 


Sent by function key f 1 
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key flO, 


kflO 


ka 


key f2, 


kf2 


k2 


key f3, 


kf3 


k3 


key f4, 


kf4 


k4 


key f5, 


kf5 


k5 


key f6, 


kf6 


k6 


key f7, 


kf7 


k7 


key f8, 


kf8 


k8 


key f9, 


kf9 


k9 




khome 


kh 




kichl 


kl 




kill 


kA 


key left, 


kcubl 


kl 


key 11, 


kll 


kH 


kev nnaee 


knp 


kN 


kev nna oe 




kP 


key right, 


kcufl 


kr 




kind 


kF 


keyir 


kri 


kR 




khts 


kT 






ku 




rmkx 


ke 


keypad xtnit, 


smkx 


ks 


lab fO 


lfO 


10 


lab fl, 


lfl 


11 


lab flO 


If 10 


la 


lab f2, 


lf2 


12 


lab f3, 


lf3 


13 


lab f4 


lf4 


14 


lab f5 


lf5 


15 


lab f6, 


lf6 


16 


lab f7, 


in 


17 


lab f8 


lfS 
110 


18 


lab_f9, 


lf9 


19 


metaon, 


smm 


mm 


metaoff, 


rmm 


mo 


newline, 


nel 


nw 


padchar, 


pad 


pc 


parmdch, 


dch 


DC 


parm_delete_line, 


dl 


DL 
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Sent by function key flO 
Sent by function key f2 
Sent by function key f3 
Sent by function key f4 
Sent by function key f5 
Sent by function key f6 
Sent by function key f7 
Sent by function key f8 
Sent by function key f9 
Sent by home key 

Sent by ins char/enter ins mode key 

Sent by insert line 

Sent by terminal left arrow key 

Sent by home-down key 

Sent by next-page key 

Sent by previous-page key 

Sent by terminal right arrow key 

Sent by scroll-forward/down key 

Sent by scroll-backward/up key 

Sent by set-tab key 

Sent by terminal up arrow key 

Out of "keypad transmit" mode 

Put terminal in "keypad transmit" mode 



Labels 


on 


function 


key 


fO if not fO 


Labels 


on 


function 


key 


f 1 if not f 1 


Labels 


on 


function 


key 


flO if not flO 


Labels 


on 


function 


key 


f2 if not f2 


Labels 


on 


function 


key 


f3 if not f3 


Labels 


on 


function 


key 


f4 if not f4 


Labels 


on 


function 


key 


f5 if not f5 


Labels 


on 


function 


key 


f6 if not f6 


Labels 


on 


function 


key 


f7 if not f7 


Labels 


on 


function 


key 


f8 if not f8 


Labels 


on 


function 


key 


f9 if not f9 



Turn on "meta mode" (8th bit) 

Turn off "meta mode" 

Newline (behaves like cr followed by If) 

Pad character (rather than null) 

Delete #1 chars (PG*) 

Delete #1 lines (PG*) 
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parm down cursor, 


cud 


DO 


Move cursor down #1 lines (PG*) 


parm_ich, 


ich 


IC 


Insert #1 blank chars (PG*) 


parmjndex, 


indn 


SF 


Scroll forward #1 lines (PG) 


parmjnsertline, 


il 


AL 


Add #1 new blank lines (PG*) 


parm_left cursor, 


cub 


LE 


Move cursor left #1 spaces (PG) 


parm_right_cursor, 


cuf 


RI 


Move cursor right #1 spaces (PG*) 


parm_rindex, 


rin 


SR 


Scroll backward #1 lines (PG) 


parm_up_cursor, 


cuu 


UP 


Move cursor up #1 lines (PG*) 


pkey_key, 


pfkey 


pk 


Prog funct key #1 to type string #2 


pkey local, 


pfloc 


pi 


Prog funct key #1 to execute string #2 


pkey_xmit, 


pfx 


px 


Prog funct key #1 to xmit string #2 


print_screen, 


mcO 


ps 


Print contents of the screen 


prtr off, 


mc4 


pf 


Turn off the printer 


prtron, 


mc5 


po 


Turn on the printer 


repeat char, 


rep 


rp 


Repeat char #1 #2 times. (PG*) 


reset 1 string, 


rsl 


rl 


Reset terminal completely to sane modes. 


reset 2string, 


rs2 


r2 


Reset terminal completely to sane modes. 


reset 3string, 


rs3 


r3 


Reset terminal completely to sane modes. 


reset file, 


rf 


rf 


Name of file containing reset string 


restore cursor, 


rc 


rc 


Restore cursor to position of last sc 


row_address, 


vpa 


cv 


Vertical position absolute (set row) (PG) 


save cursor, 


sc 


sc 


Save cursor position (P) 


scroll forward, 


ind 


sf 


Scroll text up (P) 


scroll_reverse, 


ri 


sr 


Scroll text down (P) 


setattributes, 


sgr 


sa 


Define the video attributes (PG9) 


settab, 


hts 


St 


Set a tab in all rows, current column 


setwindow, 


wind 


wi 


Current window is lines #l-#2 cols #3-#4 


tab, 


ht 


ta 


Tab to next 8 space hardware tab stop 


to_status_line, 


tsl 


ts 


Go to status line, column #1 


underline_char, 


uc 


uc 


Underscore one char and move past it 


up half line, 


hu 


hu 


Half-line up (reverse 1/2 linefeed) 


init_prog, 


iprog 


iP 


Path name of program for init 


keyal, 


kal 


Kl 


Upper left of keypad 


key_a3, 


ka3 


K3 


Upper right of keypad 


key_b2, 


kb2 


K2 


Center of keypad 


key_cl, 


kcl 


K4 


Lower left of keypad 


key_c3, 


kc3 


K5 


Lower right of keypad 


prtrnon, 


mc5p 


PO 


Turn on the printer for #1 bytes 



A Sample Entry 

The following entry, which describes the Concept— 100, is among 
the more complex entries in the terminfo file as of this writing. 



402— System Calls and Library Routines 



UNIX Programmer's Manual 



TERMINFOC4) 



TERMINFO(4) 



concept 1 00 1 c 1 00| concept | c 1 04 1 c 1 00-4p | concept 1 00, 

am, bel-"G, blank-\EH, blink-\EC, clear- A L$<2*>, cnorm-\Ew, 
cols#80, cr-"M$<9>, cubl-*H, cudl-"J, cufl-\E-, 
cup-\Ea%pl%' '%+%c%p2%' '%+%c, 

cuul-\E;, cwis-\EW, db, dchl-\E A A$<16*>, dim-\EE, dll-\E"B$<3*>, 
ed-\E*C$<16*>, el-\E"U$<16>, eo, flash-\Ek$<20>\EK, ht-\t$<8>, 
ill-\E"R$<3*>, in, ind-"J, .ind-\F$<9>, ip-$<16*>, 
is2-\ElAEf\E7\E5\E8\El\ENH\EK\E\200\Eo&\200\Eo\47\E, 
kbs-'h, kcubl-\E>, kcudl-\E<, kcufl-\E-, kcuul-\E;, 
kfl-\E5, kf2-\E6, kf3-\E7, khome-\E?, 

lines#24, mir, pb#9600, prot-\EI, rep-\Er%pl%c%p2%' '%+%c$<.2*>, 
rev-\ED, rmcup-\Ev $ < 6 > \Ep\r\n, rmir-\E\200, rmkx-\Ex, 
rmso-\Ed\Ee, rmul-\Eg, rmul-\Eg, sgrO-\EN\200, 
smcup-\EU\Ev 8p\Ep\r, smir-\E"P, smkx-\EX, smso-\EE\ED, 
smul-\EG, tabs, ul, vt#8, xenl, 

Entries may continue onto multiple lines by placing white space at 
the beginning of each line except the first. Comments may be 
included on lines beginning with "#". Capabilities in terminfo are 
of three types: Boolean capabilities which indicate that the termi- 
nal has some particular feature, numeric capabilities giving the 
size of the terminal or the size of particular delays, and string 
capabilities, which give a sequence which can be used to perform 
particular terminal operations. 

Types of Capabilities 

All capabilities have names. For instance, the fact that the Con- 
cept has automatic margins (i.e., an automatic return and linefeed 
when the end of a line is reached) is indicated by the capability 
am. Hence the description of the Concept includes am. Numeric 
capabilities are followed by the character '#' and then the value. 
Thus cols, which indicates the number of columns the terminal 
has, gives the value '80' for the Concept. 

Finally, string valued capabilities, such as el (clear to end of line 
sequence) are given by the two-character code, an '=', and then a 
string ending at the next following A delay in milliseconds 
may appear anywhere in such a capability, enclosed in $<..> 
brackets, as in el=\EK$ < 3 > , and padding characters are supplied 
by tputs to provide this delay. The delay can be either a number, 
e.g., '20', or a number followed by an '*', i.e., '3*'. A '*' indicates 
that the padding required is proportional to the number of lines 
affected by the operation, and the amount given is the per- 
affected-unit padding required. (In the case of insert character, 
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the factor is still the number of lines affected. This is always one 
unless the terminal has xenl and the software uses it.) When a '*' 
is specified, it is sometimes useful to give a delay of the form '3.5' 
to specify a delay per unit to tenths of milliseconds. (Only one 
decimal place is allowed.) 

A number of escape sequences are provided in the string valued 
capabilities for easy encoding of characters there. Both \E and \e 
map to an ESCAPE character, maps to a control-x for any 
appropriate x, and the sequences \n \1 \r \t \b \f \s give a newline, 
linefeed, return, tab, backspace, formfeed, and space. Other 
escapes include V for \\ for \, \, for comma, \: for :, and \0 for 
null. (\0 will produce \200, which does not terminate a string but 
behaves as a null character on most terminals.) Finally, charac- 
ters may be given as three octal digits after a \. 

Sometimes individual capabilities must be commented out. To do 
this, put a period before the capability name. For example, see the 
second ind in the example above. 

Preparing Descriptions 

We now outline how to prepare descriptions of terminals. The 
most effective way to prepare a terminal description is by imitating 
the description of a similar terminal in terminfo and to build up a 
description gradually, using partial descriptions with vi to check 
that they are correct. Be aware that a very unusual terminal may 
expose deficiencies in the ability of the terminfo file to describe it 
or bugs in vi. To easily test a new terminal description you can set 
the environment variable TERMINFO to a pathname of a direc- 
tory containing the compiled description you are working on and 
programs will look there rather than in lusrllib/terminfo . To get 
the padding for insert line right (if the terminal manufacturer did 
not document it) a severe test is to edit /etc/passwd at 9600 baud, 
delete 16 or so lines from the middle of the screen, then hit the V 
key several times quickly. If the terminal messes up, more pad- 
ding is usually needed. A similar test can be used for insert char- 
acter. 

Basic Capabilities 

The number of columns on each line for the terminal is given by 
the cols numeric capability. If the terminal is a CRT, then the 
number of lines on the screen is given by the lines capability. If 
the terminal wraps around to the beginning of the next line when 
it reaches the right margin, then it should have the am capability. 
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If the terminal can clear its screen, leaving the cursor in the home 
position, then this is given by the clear string capability. If the 
terminal overstrikes (rather than clearing a position when a char- 
acter is struck over) then it should have the os capability. If the 
terminal is a printing terminal, with no soft copy unit, give it both 
he and os. (os applies to storage scope terminals, such as TEK- 
TRONIX 4010 series, as well as hard copy and APL terminals.) If 
there is a code to move the cursor to the left edge of the current 
row, give this as cr. (Normally this will be carriage return, control 
M.) If there is a code to produce an audible signal (bell, beep, 
etc) give this as bel. 

If there is a code to move the cursor one position to the left (such 
as backspace) that capability should be given as cubl. Similarly, 
codes to move to the right, up, and down should be given as cufl, 
cuul, and cudl. These local cursor motions should not alter the 
text they pass over, for example, you would not normally use 
'cufl= ' because the space would erase the character moved over. 

A very important point here is that the local cursor motions 
encoded in terminfo are undefined at the left and top edges of a 
CRT terminal. Programs should never attempt to backspace 
around the left edge, unless bw is given, and never attempt to go 
up locally off the top. In order to scroll text up, a program will go 
to the bottom left corner of the screen and send the ind (index) 
string. 

To scroll text down, a program goes to the top left corner of the 
screen and sends the ri (reverse index) string. The strings ind and 
ri are undefined when not on their respective corners of the screen. 

Parameterized versions of the scrolling sequences are indn and rin 
which have the same semantics as ind and ri except that they take 
one parameter, and scroll that many lines. They are also 
undefined except at the appropriate edge of the screen. 

The am capability tells whether the cursor sticks at the right edge 
of the screen when text is output, but this does not necessarily 
apply to a cufl from the last column. The only local motion which 
is defined from the left edge is if bw is given, then a cubl from the 
left edge will move to the right edge of the previous row. If bw is 
not given, the effect is undefined. This is useful for drawing a box 
around the edge of the screen, for example. If the terminal has 
switch selectable automatic margins, the terminfo file usually 
assumes that this is on; i.e., am. If the terminal has a command 
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which moves to the first column of the next line, that command 
can be given as nel (newline). It does not matter if the command 
clears the remainder of the current line, so if the terminal has no 
cr and If it may still be possible to craft a working nel out of one 
or both of them. 

These capabilities suffice to describe hardcopy and glass-tty termi- 
nals. Thus the model 33 teletype is described as 

33 ! tty33 ! tty ! model 33 teletype, 

bel=~G, cols#72, cr= A M, cud1= A J, he, ind= " J , os, 

while the Lear Siegler ADM— 3 is described as 

adm3 ! 3 ! lsi adm3 , 

am, bel = "G , clear = A Z, cols#80, cr= A M, cub 1 = *H , cud1 = ~J, 
ind = ' y J, lines#24, 

Parameterized Strings 

Cursor addressing and other strings requiring parameters in the 
terminal are described by a parameterized string capability, with 
print/ (3S) like escapes % x in it. For example, to address the cur- 
sor, the cup capability is given, using two parameters: the row and 
column to address to. (Rows and columns are numbered from 
zero and refer to the physical screen visible to the user, not to any 
unseen memory.) If the terminal has memory relative cursor 
addressing, that can be indicated by mrcup. 

The parameter mechanism uses a stack and special % codes to 
manipulate it. Typically a sequence will push one of the parame- 
ters onto the stack and then print it in some format. Often more 
complex operations are necessary. 

The % encodings have the following meanings: 



%% 


outputs '%' 


%d 


print pop() as in printf 


%2d 


print popO like %2d 


%3d 


print popO like %3d 


%02d 




%03d 


as in printf 


%c 


print popO gives %c 


%s 


print popO gives %s 


%ptl-9] 


push ith parm 


%P[a-z] 


set variable [a-zl to popO 


%g[a-z] 


get variable [a-zl and push it 
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char constant c 
integer constant nn 



%+ %- %* %/ %m 



%& %| %" 
%- %> %< 
%\ %~ 
%i 



arithmetic (%m is mod): push (pop 0 op popO) 
bit operations: push (pop 0 op popO) 
logical operations: push (pop 0 op popO) 
unary operations push (op popO) 
add 1 to first two parms (for ANSI terminals) 



%? expr %t thenpart %e elsepart %; 



if-then-else, %e elsepart is optional, 
else-ifs are possible ala Algol 68: 

%? Cj %t bj %e c 2 %t b 2 %e c 3 %t b 3 %e c 4 %t b 4 %e %; 
c- are conditions, b. are bodies. 



Binary operations are in postfix form with the operands in the 
usual order. That is, to get x-5 one would use "%gx%{5}%-". 

Consider the Hewlett-Packard 2645, which, to get to row 3 and 
column 12, needs to be sent \E&al2c03Y padded for 6 mil- 
liseconds. Note that the order of the rows and columns is inverted 
here, and that the row and column are printed as two digits. Thus 
its cup capability is cup=6\E&%p2%2dc%pl%2dY. 

The Microterm ACT-IV needs the current row and column sent 
preceded by a "T, with the row and column simply encoded in 
binary, cup=~T%pl%c%p2%c. Terminals which use %c need to be 
able to backspace the cursor (cubl), and to move the cursor up 
one line on the screen (cuul). This is necessary because it is not 
always safe to transmit \n "D and \r, as the system may change or 
discard them. (The library routines dealing with terminfo set tty 
modes so that tabs are never expanded, so \t is safe to send. This 
turns out to be essential for the Ann Arbor 4080.) 

A final example is the LSI ADM-3a, which uses row and column 
offset by a blank character, thus cup=\E=%pl%' '%+%c%p2%' 
'%+%c. After sending *\E— ', this pushes the first parameter, 
pushes the ASCII value for a space (32), adds them (pushing the 
sum on the stack in place of the two previous values) and outputs 
that value as a character. Then the same is done for the second 
parameter. More complex arithmetic is possible using the stack. 

If the terminal has row or column absolute cursor addressing, 
these can be given as single parameter capabilities hpa (horizontal 
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position absolute) and vpa (vertical position absolute). Sometimes 
these are shorter than the more general two parameter sequence 
(as with the hp2645) and can be used in preference to cup . If 
there are parameterized local motions (e.g., move n spaces to the 
right) these can be given as cud, cub, cuf, and cuu with a single 
parameter indicating how many spaces to move. These are pri- 
marily useful if the terminal does not have cup, such as the TEK- 
TRONIX 4025. 

Cursor Motions 

If the terminal has a fast way to home the cursor (to very upper 
left corner of screen) then this can be given as home; similarly a 
fast way of getting to the lower left-hand corner can be given as 11; 
this may involve going up with cuul from the home position, but a 
program should never do this itself (unless U does) because it can 
make no assumption about the effect of moving up from the home 
position. Note that the home position is the same as addressing to 
(0,0): to the top left corner of the screen, not of memory. (Thus, 
the \EH sequence on Hewlett-Packard terminals cannot be used 
for home.) 

Area Clears 

If the terminal can clear from the current position to the end of 
the line, leaving the cursor where it is, this should be given as el. 
If the terminal can clear from the current position to the end of 
the display, then this should be given as ed. Ed is only defined 
from the first column of a line. (Thus, it can be simulated by a 
request to delete a large number of lines, if a true ed is not avail- 
able.) 

Insert/delete line 

If the terminal can open a new blank line before the line where the 
cursor is, this should be given as ill; this is done only from the first 
position of a line. The cursor must then appear on the newly 
blank line. If the terminal can delete the line which the cursor is 
on, then this should be given as dll; this is done only from the first 
position on the line to be deleted. Versions of ill and dll which 
take a single parameter and insert or delete that many lines can be 
given as il and dl. If the terminal has a settable scrolling region 
(like the vtlOO) the command to set this can be described with the 
csr capability, which takes two parameters: the top and bottom 
lines of the scrolling region. The cursor position is, alas, undefined 
after using this command. It is possible to get the effect of insert 
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or delete line using this command — the sc and rc (save and 
restore cursor) commands are also useful. Inserting lines at the 
top or bottom of the screen can also be done using ri or ind on 
many terminals without a true insert/delete line, and is often fas- 
ter even on terminals with those features. 

If the terminal has the ability to define a window as part of 
memory, which all commands affect, it should be given as the 
parameterized string wind. The four parameters are the starting 
and ending lines in memory and the starting and ending columns 
in memory, in that order. 

If the terminal can retain display memory above, then the da capa- 
bility should be given; if display memory can be retained below, 
then db should be given. These indicate that deleting a line or 
scrolling may bring non-blank lines up from below or that scrolling 
back with ri may bring down non-blank lines. 

Insert/Delete Character 

There are two basic kinds of intelligent terminals with respect to 
insert/delete character which can be described using terminfo. The 
most common insert/delete character operations affect only the 
characters on the current line and shift characters off the end of 
the line rigidly. Other terminals, such as the Concept 100 and the 
Perkin Elmer Owl, make a distinction between typed and untyped 
blanks on the screen, shifting upon an insert or delete only to an 
untyped blank on the screen which is either eliminated, or 
expanded to two untyped blanks. You can determine the kind of 
terminal you have by clearing the screen and then typing text 
separated by cursor motions. Type abc def using local cursor 
motions (not spaces) between the abc and the def. Then position 
the cursor before the abc and put the terminal in insert mode. If 
typing characters causes the rest of the line to shift rigidly and 
characters to fall off the end, then your terminal does not distin- 
guish between blanks and untyped positions. If the abc shifts over 
to the def which then move together around the end of the current 
line and onto the next as you insert, you have the second type of 
terminal, and should give the capability in, which stands for insert 
null. While these are two logically separate attributes (one line vs. 
multiline insert mode, and special treatment of untyped spaces) we 
have seen no terminals whose insert mode cannot be described with 
the single attribute. 
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Terminfo can describe both terminals which have an insert mode, 
and terminals which send a simple sequence to open a blank posi- 
tion on the current line. Give as smir the sequence to get into 
insert mode. Give as rmir the sequence to leave insert mode. Now 
give as ichl any sequence needed to be sent just before sending the 
character to be inserted. Most terminals with a true insert mode 
will not give ichl; terminals which send a sequence to open a 
screen position should give it here. (If your terminal has both, 
insert mode is usually preferable to ichl. Do not give both unless 
the terminal actually requires both to be used in combination.) If 
post insert padding is needed, give this as a number of milliseconds 
in ip (a string option). Any other sequence which may need to be 
sent after an insert of a single character may also be given in ip. 
If your terminal needs both to be placed into an 'insert mode' and 
a special code to precede each inserted character, then both 
simr/rmir and ichl can be given, and both will be used. The ich 
capability, with one parameter, «, will repeat the effects of ichl n 
times. 

It is occasionally necessary to move around while in insert mode to 
delete characters on the same line (e.g., if there is a tab after the 
insertion position). If your terminal allows motion while in insert 
mode you can give the capability mir to speed up inserting in this 
case. Omitting mir will affect only speed. Some terminals (not- 
ably Datamedia's) must not have mir because of the way their 
insert mode works. 

Finally, you can specify dchl to delete a single character, dch with 
one parameter, n, to delete n characters, and delete mode by giv- 
ing smdc and rmdc to enter and exit delete mode (any mode the 
terminal needs to be placed in for dchl to work) . 

A command to erase n characters (equivalent to outputting n 
blanks without moving the cursor) can be given as ech with one 
parameter. 

Highlighting, Underlining, and Visible Bells 

If your terminal has one or more kinds of display attributes, these 
can be represented in a number of different ways. You should 
choose one display form as standout mode, representing a good, 
high contrast, easy-on-the-eyes, format for highlighting error mes- 
sages and other attention getters. (If you have a choice, reverse 
video plus half-bright is good, or reverse video alone.) The 
sequences to enter and exit standout mode are given as smso and 
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rmso, respectively. If the code to change into or out of standout 
mode leaves one or even two blank spaces on the screen, as the 
TVI 912 and Teleray 1061 do, then xmc should be given to tell 
how many spaces are left. 

Codes to begin underlining and end underlining can be given as 
smul and rmul respectively. If the terminal has a code to underline 
the current character and move the cursor one space to the right, 
such as the Microterm Mime, this can be given as uc. 

Other capabilities to enter various highlighting modes include blink 
(blinking) bold (bold or extra bright) dim (dim or half-bright) 
invis (blanking or invisible text) prot (protected) rev (reverse 
video) sgrO (turn off all attribute modes) smacs (enter alternate 
character set mode) and rmacs (exit alternate character set mode) . 
Turning on any of these modes singly may or may not turn off 
other modes. 

If there is a sequence to set arbitrary combinations of modes, this 
should be given as sgr (set attributes), taking 9 parameters. Each 
parameter is either 0 or 1, as the corresponding attribute is on or 
off. The 9 parameters are, in order: standout, underline, reverse, 
blink, dim, bold, blank, protect, alternate character set. Not all 
modes need be supported by sgr, only those for which correspond- 
ing separate attribute commands exist. 

Terminals with the "magic cookie" glitch (xmc) deposit special 
"cookies" when they receive mode-setting sequences, which affect 
the display algorithm rather than having extra bits for each char- 
acter. Some terminals, such as the Hewlett-Packard 2621, 
automatically leave standout mode when they move to a new line 
or the cursor is addressed. Programs using standout mode should 
exit standout mode before moving the cursor or sending a newline, 
unless the msgr capability, asserting that it is safe to move in stan- 
dout mode, is present. 

If the terminal has a way of flashing the screen to indicate an 
error quietly (a bell replacement) then this can be given as flash; it 
must not move the cursor. 

If the cursor needs to be made more visible than normal when it is 
not on the bottom line (to make, for example, a non-blinking 
underline into an easier to find block or blinking underline) give 
this sequence as cvvis. If there is a way to make the cursor com- 
pletely invisible, give that as civis. The capability cnorm should be 
given which undoes the effects of both of these modes. 
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If the terminal needs to be in a special mode when running a pro- 
gram that uses these capabilities, the codes to enter and exit this 
mode can be given as smcup and rmcup. This arises, for example, 
from terminals like the Concept with more than one page of 
memory. If the terminal has only memory relative cursor address- 
ing and not screen relative cursor addressing, a one screen-sized 
window must be fixed into the terminal for cursor addressing to 
work properly. This is also used for the TEKTRONIX 4025, where 
smcup sets the command character to be the one used by terminfo. 

If your terminal correctly generates underlined characters (with no 
special codes needed) even though it does not overstrike, then you 
should give the capability id. If overstrikes are erasable with a 
blank, then this should be indicated by giving eo. 

Keypad 

If the terminal has a keypad that transmits codes when the keys 
are pressed, this information can be given. Note that it is not pos- 
sible to handle terminals where the keypad only works in local 
(this applies, for example, to the unshifted Hewlett-Packard 2621 
keys). If the keypad can be set to transmit or not transmit, give 
these codes as smkx and rmkx. Otherwise the keypad is assumed 
to always transmit. The codes sent by the left arrow, right arrow, 
up arrow, down arrow, and home keys can be given as kcubl, 
kcufl, kcuul, kcudl, and khome respectively. If there are function 
keys such as fO, fl, flO, the codes they send can be given as 
kfO, kfl, kflO. If these keys have labels other than the default 
fO through flO, the labels can be given as lfO, Ifl, If 10. The 
codes transmitted by certain other special keys can be given: kll 
(home down), kbs (backspace), ktbc (clear all tabs), kctab (clear 
the tab stop in this column), kclr (clear screen or erase key), 
kdchl (delete character), kdll (delete line), krmir (exit insert 
mode), kel (clear to end of line), ked (clear to end of screen), 
kichl (insert character or enter insert mode), kill (insert line), 
knp (next page), kpp (previous page), kind (scroll forward/down), 
kri (scroll backward/up), khts (set a tab stop in this column). In 
addition, if the keypad has a 3 by 3 array of keys including the 
four arrow keys, the other five keys can be given as kal, ka3, kb2, 
kcl, and kc3. These keys are useful when the effects of a 3 by 3 
directional pad are needed. 
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Tabs and Initialization 

If the terminal has hardware tabs, the command to advance to the 
next tab stop can be given as ht (usually control I). A "backtab" 
command which moves leftward to the next tab stop can be given 
as cbt. By convention, if the teletype modes indicate that tabs are 
being expanded by the computer rather than being sent to the ter- 
minal, programs should not use ht or cbt even if they are present, 
since the user may not have the tab stops properly set. If the ter- 
minal has hardware tabs which are initially set every n spaces 
when the terminal is powered up, the numeric parameter it is 
given, showing the number of spaces the tabs are set to. This is 
normally used by the tset command to determine whether to set 
the mode for hardware tab expansion, and whether to set the tab 
stops. If the terminal has tab stops that can be saved in nonvola- 
tile memory, the terminfo description can assume that they are 
properly set. 

Other capabilities include isl, is2, and is3, initialization strings for 
the terminal, iprog, the path name of a program to be run to ini- 
tialize the terminal, and if, the name of a file containing long ini- 
tialization strings. These strings are expected to set the terminal 
into modes consistent with the rest of the terminfo description. 
They are normally sent to the terminal, by the tset program, each 
time the user logs in. They will be printed in the following order: 
isl; is2; setting tabs using tbc and hts; if; running the program 
iprog; and finally is3. Most initialization is done with is2. Special 
terminal modes can be set up without duplicating strings by put- 
ting the common sequences in is2 and special cases in isl and is3. 
A pair of sequences that does a harder reset from a totally unk- 
nown state can be analogously given as rsl, rs2, rf, and rs3, analo- 
gous to is2 and if. These strings are output by the reset program, 
which is used when the terminal gets into a wedged state. Com- 
mands are normally placed in rs2 and rf only if they produce 
annoying effects on the screen and are not necessary when logging 
in. For example, the command to set the vtlOO into 80-column 
mode would normally be part of is2, but it causes an annoying 
glitch of the screen and is not normally needed since the terminal 
is usually already in 80 column mode. 

If there are commands to set and clear tab stops, they can be given 
as tbc (clear all tab stops) and hts (set a tab stop in the current 
column of every row). If a more complex sequence is needed to 
set the tabs than can be described by this, the sequence can be 
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placed in is2 or if. 
Delays 

Certain capabilities control padding in the teletype driver. These 
are primarily needed by hard copy terminals, and are used by the 
tset program to set teletype modes appropriately. Delays embed- 
ded in the capabilities cr, ind, cubl, ff, and tab will cause the 
appropriate delay bits to be set in the teletype driver. If pb (pad- 
ding baud rate) is given, these values can be ignored at baud rates 
below the value of pb. 

Miscellaneous 

If the terminal requires other than a null (zero) character as a 
pad, then this can be given as pad. Only the first character of the 
pad string is used. 

If the terminal has an extra "status line" that is not normally used 
by software, this fact can be indicated. If the status line is viewed 
as an extra line below the bottom line, into which one can cursor 
address normally (such as the Heathkit hl9's 25th line, or the 
24th line of a vtlOO which is set to a 23 -line scrolling region), the 
capability hs should be given. Special strings to go to the begin- 
ning of the status line and to return from the status line can be 
given as tsl and fsl. (fsl must leave the cursor position in the same 
place it was before tsl. If necessary, the sc and rc strings can be 
included in tsl and fsl to get this effect.) The parameter tsl takes 
one parameter, which is the column number of the status line the 
cursor is to be moved to. If escape sequences and other special 
commands, such as tab, work while in the status line, the flag 
eslok can be given. A string which turns off the status line (or 
otherwise erases its contents) should be given as dsl. If the termi- 
nal has commands to save and restore the position of the cursor, 
give them as sc and rc. The status line is normally assumed to be 
the same width as the rest of the screen, e.g., cols. If the status 
line is a different width (possibly because the terminal does not 
allow an entire line to be loaded) the width, in columns, can be 
indicated with the numeric parameter wsl. 

If the terminal can move up or down half a line, this can be indi- 
cated with hu (half-line up) and hd (half-line down). This is pri- 
marily useful for superscripts and subscripts on hardcopy termi- 
nals. If a hardcopy terminal can eject to the next page (form 
feed), give this as ff (usually control L). 
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If there is a command to repeat a given character a given number 
of times (to save time transmitting a large number of identical 
characters) this can be indicated with the parameterized string 
rep. The first parameter is the character to be repeated and the 
second is the number of times to repeat it. Thus, 
tparm(repeat_char, 'x\ 10) is the same as 'xxxxxxxxxx'. 

If the terminal has a settable command character, such as the 
TEKTRONIX 4025, this can be indicated with cmdch. A prototype 
command character is chosen which is used in all capabilities. 
This character is given in the cmdch capability to identify it. The 
following convention is supported on some UNIX systems: The 
environment is to be searched for a CC variable, and if found, all 
occurrences of the prototype character are replaced with the char- 
acter in the environment variable. 

Terminal descriptions that do not represent a specific kind of 
known terminal, such as switch, dialup, patch, and network, 
should include the gn (generic) capability so that programs can 
complain that they do not know how to talk to the terminal. (This 
capability does not apply to virtual terminal descriptions for which 
the escape sequences are known.) 

If the terminal uses xon/xofF handshaking for flow control, give 
xon. Padding information should still be included so that routines 
can make better decisions about costs, but actual pad characters 
will not be transmitted. 

If the terminal has a "meta key" which acts as a shift key, setting 
the 8th bit of any character transmitted, this fact can be indicated 
with km. Otherwise, software will assume that the 8th bit is par- 
ity and it will usually be cleared. If strings exist to turn this 
"meta mode" on and off, they can be given as smm and rmm. 

If the terminal has more lines of memory than will fit on the 
screen at once, the number of lines of memory can be indicated 
with lm. A value of lm#0 indicates that the number of lines is not 
fixed, but that there is still more memory than fits on the screen. 

If the terminal is one of those supported by the UNIX system vir- 
tual terminal protocol, the terminal number can be given as vt. 

Media copy strings which control an auxiliary printer connected to 
the terminal can be given as mcO: print the contents of the screen, 
mc4: turn off the printer, and mc5: turn on the printer. When 
the printer is on, all text sent to the terminal will be sent to the 
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printer. It is undefined whether the text is also displayed on the 
terminal screen when the printer is on. A variation mc5p takes 
one parameter, and leaves the printer on for as many characters as 
the value of the parameter, then turns the printer off. The param* 
eter should not exceed 255. All text, including mc4, is tran- 
sparently passed to the printer while an mc5p is in effect. 

Strings to program function keys can be given as pfkey, pfloc, and 
pfx. Each of these strings takes two parameters: the function key 
number to program (from 0 to 10) and the string to program it 
with. Function key numbers out of this range may program 
undefined keys in a terminal dependent manner. The difference 
between the capabilities is that pfkey causes pressing the given key 
to be the same as the user typing the given string; pfloc causes the 
string to be executed by the terminal in local; and pfx causes the 
string to be transmitted to the computer. 

Glitches and Braindamage 

Hazeltine terminals, which do not allow characters to be 
displayed should indicate hz. 

Terminals which ignore a linefeed immediately after an am wrap, 
such as the Concept and vtlOO, should indicate xenl. 

If el is required to get rid of standout (instead of merely writing 
normal text on top of it), xhp should be given. 

Teleray terminals, where tabs turn all characters moved over to 
blanks, should indicate xt (destructive tabs). This glitch is also 
taken to mean that it is not possible to position the cursor on top 
of a "magic cookie", that to erase standout mode it is instead 
necessary to use delete and insert line. 

The Beehive Superbee, which is unable to correctly transmit the 
escape or control C characters, has xsb, indicating that the fl key 
is used for escape and f2 for control C. (Only certain Super bees 
have this problem, depending on the ROM.) 

Other specific terminal problems may be corrected by adding more 
capabilities of the form xx. 

Similar Terminals 

If there are two very similar terminals, one can be defined as being 
just like the other with certain exceptions. The string capability 
use can be given with the name of the similar terminal. The capa- 
bilities given before use override those in the terminal type invoked 
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by use. A capability can be cancelled by placing xx@ to the left 
of the capability definition, where xx is the capability. For exam- 
ple, the entry 

2621-nl, smkx@, rmkx@, use— 2621, 

defines a 2621-nl that does not have the smkx or rmkx capabilities, 
and hence does not turn on the function key labels when in visual 
mode. This is useful for different modes for a terminal, or for 
different user preferences. 

FILES 

/usr/lib/terminfo/?/* files containing terminal descriptions 

SEE ALSO 

curses (3X), printf(3S), term (5). 

tic(lM) in the UNIX Programmer's Manual— Volume 3: System 
Administration Facilities. 
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NAME 



utmp, wtmp — utmp and wtmp entry formats 



SYNOPSIS 

#include <sys/types.h> 
#include <utmp.h> 

DESCRIPTION 

These files, which hold user and accounting information for such 
commands as who (I), write (1), and login (l), have the following 
structure as defined by <utmp.h>: 



#define 
#define 
#define 



UTMP_FILE 
WTMPJFILE 
ut name 



7etc/utmp" 
7etc/wtmp" 
ut user 



struct utmp { 
char 
char 
char 
short 
short 
struct 
short 
short 
} ut_exit; 



ut_user[8l; 

ut_id[4l; 

ut_line[l2]; 

ut_pid; 

ut_type; 

exit_status { 

etermination; 

eexit; 



timet uttime; 



/* User login name */ 

/♦ /etc/inittab id (usually line #) */ 

/* device name (console, lnxx) */ 

/* process id */ 

/* type of entry •/ 

/* Process termination status */ 
/* Process exit status */ 
/* The exit status of a process 
* marked as DEAD PROCESS. */ 
/* time entry was made */ 



/* Definitions for ut type */ 

#define EMPTY 0 

#define RUNJLVL 1 

#define BOOT_TIME 2 

#define OLD_TIME 3 

#define NEW_TIME 4 

#define INIT_PROCESS 5 

#define LOGIN_PROCESS 6 

#define USER_PROCESS 7 

#define DEAD_PROCESS 8 

#define ACCOUNTING 9 

#define UTMAXTYPE ACCOUNTING 
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/* Special strings or formats used in the "utline" field when */ 

/* accounting for something other than a process */ 

/* No string for the ut line field can be more than 1 1 chars + */ 

/* a NULL in length */ 

#define RUNLVL MSG "run-level %c" 

#define BOOT_MSG "system boot" 

#define OTIME MSG "old time" 

#define NTIMEMSG "new time" 

FILES 

/usr/include/utmp.h 

/etc/utmp 

/etc/wtmp 

SEE ALSO 

getut(3C). 

login(l), who(l), write(l) in the UNIX Programmer's Manual— 
Volume I: Commands and Utilities. 
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NAME 

intro — introduction to miscellany 
DESCRIPTION 

This section describes miscellaneous facilities such as macro pack- 
ages, character set tables, etc. 
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NAME 

ascii — map of ASCII character set 

SYNOPSIS 

cat /usr/pub/ascii 

DESCRIPTION 

Ascii is a map of the ASCII character set, giving both octal and 
hexadecimal equivalents of each character, to be printed as 
needed. It contains: 



000 mil 


001 

\J\J 1 


OVJIl 


009 ctv 

UUZ SLA 


uuj eix 


004 ent 


00 5 


pnn 
CHlf 


006 ctrV 


UU / Del 


010 bs 


01 1 

Ul 1 


ht 

11 L 


01 9 nl 

U 1 Z Ill 


01 1 vt 


014 np 


01 5 


VI 


01 6 «f» 


01 7 ci 

Ul / SI 


020 die 


021 


del 


099 Hr9 


091 rlrl 

UZ.J UWJ 


024 dc4 




Haft. 


096 cvn 

uzaj syn 


097 <»th 
uz / eio 


0^0 ran 


011 


CHI 




UJJ CSC 


034 fs 


035 


no 


036 r«t 

UJU 1 0 


017 11c 
UJ / us 


040 sn 


041 


| 


049 " 


041 a 


044 $ 


04^ 


/o 


046 # 


047 ' 


050 ( 


0^1 

yj j i 


) 


0S9 * 

U JZ 


0S1 4- 


054 , 


o^s 




0S6 


057 / 


060 0 


061 


1 

J. 


069 9 


061 1 


064 4 


06 5 


«; 


066 6 


067 7 
uo / / 


070 8 


071 


9 


072 : 


073 ; 


074 < 


075 




076 > 


077 ? 


100 @ 


101 


A 


102 B 


103 C 


104 D 


105 


E 


106 F 


107 G 


110 H 


111 


I 


112 J 


113 K 


114 L 


115 


M 


116 N 


117 O 


120 P 


121 


Q 


122 R 


123 S 


124 T 


125 


u 


126 V 


127 W 


130 X 


131 


Y 


132 Z 


133 [ 


134 \ 


135 


] 


136 * 


137 


140 * 


141 


a 


142 b 


143 c 


144 d 


145 


e 


146 f 


147 g 


150 h 


151 


i 


152 j 


153 k 


154 1 


155 


m 


156 n 


157 0 


160 p 


161 


q 


162 r 


163 s 


164 t 


165 


u 


166 v 


167 w 


170 x 


171 


y 


172 z 


173 { 
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174 


175} 


176 ' 


177 del 


00 nul 


01 soh 


02 stx 


03 etx 


04 eot 


05 enq 


06 ack 


07 bel 


08 bs 


09 ht 


Oa nl 


Ob vt 


0c np 


Od cr 


Oe so 


Of si 


10 die 


11 del 


12 dc2 


13 dc3 


14dc4 


15 nak 


16 syn 


17 etb 


18 can 


19 em 


la sub 


lb esc 


lcfs 


Id gs 


le rs 


If us 


20 sp 


21 ! 


22 " 


23 # 


24 $ 


25 % 


26 & 


27 ' 


28 ( 


29) 


2a * 


2b + 


2c , 


2d - 


2e . 


2f / 


30 0 


31 1 


32 2 


33 3 


34 4 


35 5 


36 6 


37 7 


38 8 


39 9 


3a : 


3b ; 


3c < 


3d - 


3e > 


3f ? 


40 @ 


41 A 


42 B 


43 C 


44 D 


45 E 


46 F 


47 G 


48 H 


49 I 


4a J 


4b K 


4c L 


4dM 


4eN 


4f O 


50 P 


51 Q 


52 R 


53 S 


54 T 


55 U 


56 V 


57 W 


58 X 


59 Y 


5a Z 


5b [ 


5c \ 


5d] 


5e A 


5f 


60 * 


61 a 


62 b 


63 c 


64 d 


65 e 


66 f 


67 g 


68 h 


69 i 


6a j 


6b k 


6c 1 


6d m 


6e n 


6f o 


70 p 


71 q 


72 r 


73 s 


74 t 


75 u 


76 v 


77 w 


78 x 


79 y 


7a z 


7b { 


7c 


7d) 


7e ~ 


7f del 



FILES 

/usr/pub/ascii 
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NAME 

environ — user environment 
DESCRIPTION 

An array of strings called the "environment" is made available by 
exec (2) when a process begins. By convention, these strings have 
the form "name^value". The following names are used by various 
commands: 

PATH The sequence of directory prefixes that sh(l), time (I), 
nicett), nohupiX), etc., apply in searching for a file 
known by an incomplete path name. The prefixes are 
separated by colons (:). Login (1) sets 
PATH = :/bin:/usr/bin. 

HOME Name of the user's login directory, set by login (l) from 
the password file passwd (4) . 

TERM The kind of terminal for which output is to be prepared. 
This information is used by commands, such as mmiX) or 
tplot (1G), which may exploit special capabilities of that 
terminal. 

TZ Time zone information. The format is xxxnzzz where xxx 
is standard local time zone abbreviation, n is the 
difference in hours from GMT, and zzz is the abbreviation 
for the daylight-saving local time zone, if any; for exam- 
ple, EST5EDT. 

Further names may be placed in the environment by the export 
command and "name^value" arguments in sh(l), or by exec (2). 
It is unwise to conflict with certain shell variables that are fre- 
quently exported by .profile files: MAIL, PS1, PS2, IFS. 

SEE ALSO 

exec (2). 

env(l), login(l), sh(l), mm(l), nice(l), nohup(l), time(l), 
tplot(lG) in the UNIX Programmer's Manual —Volume 1: Com- 
mands and Utilities. 
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NAME 

eqnchar — special character definitions for eqn and neqn 
SYNOPSIS 

eqn /usr/pub/eqnchar [ files ] | troff [ options ] 
neqn /usr/pub/eqnchar [ files ] | nroff (1) [ options ] 
eqn -Taps /usr/pub/apseqnchar [ files ] | troff [ options ] 
eqn -Teat /usr/pub/cateqnchar [ files ] | otroff [ options ] 
DESCRIPTION 

Eqnchar contains troff (I) and nroff (l) character definitions for 
constructing characters that are not available on a phototypesetter. 
These definitions are primarily intended for use with eqn(\) and 
neqn; eqnchar contains definitions for the following characters: 



ciplus 


ciplus | | 


II 


square 


square 


citimes 


citimes langle 


langle 


circle 


circle 


wig 


wig rangle 


rangle 


blot 


blot 


-wig 


—wig hbar 


hbar 


bullet 


bullet 


>wig 


>wig ppd 


ppd 


prop 


prop 


<wig 


<wig <—> 


< — 


empty 


empty 


=wig 


=wig <=> 


<> 


member 


member 


star 


star | < 


l< 


nomem 


nomem 


bigstar 


bigstar \ > 


l> 


cup 


cup 


=dot 


=dot ang 


ang 


cap 


cap 


orsign 


orsign rang 


rang 


incl 


incl 


andsign 


andsign 3dot 


3dot 


subset 


subset 


=del 


=del thf 


thf 


supset 


supset 


oppA 


oppA quarter 


quarter Isubset 


Isubset 


oppE 


oppE ^quarter 


^quarter 


!supset\supset 


angstrom 


angstrom 


degree 


degree 


scrLscrL 













Apseqnchar is a version of eqnchar tailored for the Autologic 
APS-5 phototypesetter. This will not look optimal on other photo- 
typesetters. Similarly, cateqnehar is the old eqnchar tailored for 
the Wang CAT and the old otroff. Until a phototypesetter- 
independent version of eqnchar is available, eqnchar should be a 
link to the default version on each system. The standard default is 
apseqnchar. 
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FILES 

/usr/pub/eqnchar 

/usr/pub/apseqnchar 

/usr/pub/cateqnchar 

SEE ALSO 

eqn(l), nrofF(l), troff(l) in the UNIX Programmer's Manual— 
Volume 1: Commands and Utilities. 
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NAME 

fcntl — file control options 

SYNOPSIS 

#include <fcntl.h> 

DESCRIPTION 

The fcntl (2) function provides for control over open files. The 
include file describes requests and arguments to fcntl and 
open (2) . 

/* Flag values accessible to open (2) and fcntl (2) */ 
/* (The first three can only be set by open) */ 



#define 


0_RDONLY 


0 


#define 


CMVRONLY 


1 


#define 


0_RDWR 


2 


#define 


0_NDELAY 


04 


#define 


0_APPEND 


010 



/* Non-blocking I/O •/ 
/* append (writes guaranteed at the end) */ 

/* Flag values accessible only to open (2) */ 



#define 


0_CREAT 


00400 /* open with file create (uses third open arg) 


#define 


OJTRUNC 


01000 /• open with truncation */ 


#define 


0_EXCL 


02000 /* exclusive open */ 


/* fcntl(2) 


requests */ 






#define 


F_DUPFD 


0 


/* Duplicate fildes */ 


#define 


F GETFD 


1 


/* Get fildes flags »/ 


#define 


FJSETFD 


2 


/* Set fildes flags */ 


#define 


F GETFL 


3 


/* Get file flags •/ 


#define 


F SETFL 


4 


/* Set file flags */ 


#define 


F GETLK 


5 


/* Get blocking file locks */ 


#define 


F SETLK 


6 


/* Set or clear file locks and fail on busy */ 


#define 


F SETLKW 


7 


/•Set or clear file locks and wait on busy */ 



/* file segment locking control structure */ 
struct flock 

short l_type; 

short lwhence; 

long l_start; 

long l_len; /* if 0 then until EOF */ 

int l_pid; /• returned with F GETLK */ 

/* file segment locking types */ 
#define F_RDLCK 01 /• Read lock •/ 
#define F_WRLCK 02 /• Write lock */ 
#define F UNLCK 03 /• Remove locks */ 

SEE ALSO 

fcntl (2), open (2). 
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NAME 

font — description files for device-independent troff 

SYNOPSIS 

troff -Tptty ... 

DESCRIPTION 

For each phototypesetter supported by troff (1) and available on 
this system, there is a directory containing files describing the dev- 
ice and its fonts. This directory is named /usr/lib/font/dev/rtfy 
where ptty is the name of the phototypesetter. Currently the only 
ptty supported is aps for the Autologic APS— 5. 

For a particular phototypesetter, ptty, the ASCII file DESC in the 
directory /usr/lib/font/dev/tffy describes its characteristics. Each 
line starts with a word identifying the characteristic and followed 
by appropriate specifiers. Blank lines and lines beginning with a # 
are ignored. 

The legal lines for DESC are: 



res num 

hor num 
vert num 
unitwidth num 

sizescale num 
paperwidth num 
paperlength num 
sparel num 
spare2 num 
sizes num num .. 

fonts num name 



charset 



resolution of device in basic incre- 
ments per inch 

smallest unit of horizontal motion 

smallest unit of vertical motion 

pointsize in which widths are 
specified 

scaling for fractional pointsizes 
width of paper in basic increments 
length of paper in basic increments 
available for use 
available for use 

list of pointsizes available on 
typesetter 

number of initial fonts followed by 
the names of the fonts. For exam- 
ple: 

fonts 4 R I B S 



this always comes last in the file 
and is on a line by itself. Follow- 
ing it is the list of special character 
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names for this device. Names are 
separated by a space or a newline. 
The list can be as long as neces- 
sary. Names not in this list are 
not allowed in the font description 
files. 

Res is the basic resolution of the device in increments per inch. 
Hor and vert describe the relationships between motions in the hor- 
izontal and vertical directions. If the device is capable of moving 
in single basic increments in both directions, both hor and vert 
would have values of 1. If the vertical motions only take place in 
multiples of two basic units while the horizontal motions take place 
in the basic increments, then hor would be 1, while vert would be 
2. Unitwidth is the pointsize in which all width tables in the font 
description files are given. Troff automatically scales the widths 
from the unitwidth size to the pointsize it is working with. Sizes- 
cale is not currently used and is 1 . Paperwidth is the width of the 
paper in basic increments. The APS-5 is 6120 increments wide. 
Paperlength is the length of a sheet of paper in the basic incre- 
ments. 

For each font supported by the phototypesetter, there is also an 
ASCII file with the same name as the font (e.g., R, I, CW). The 
format for a font description file is: 

name name name of the font, such as R or CW 

internalname name internal name of font 

special sets flag indicating that the font is 

special 

ligatures name ... 0 Sets flag indicating font has liga- 
tures. The list of ligatures follows 
and is terminated by a zero. 
Accepted ligatures are: 
fif fi fl ffi ffl. 

spare 1 available for use 

spacewidth num width of space if something other 

than 1/3 of \(em is desired as a 
space. 

charset The charset must come at the end. 

Each line following the word char- 
set describes one character in the 
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font. Each line has one of two for- 
mats: 

name width kerning code 
name " 

where name is either a single ASCII character or a special 
character name from the list found in DESC. The width 
is in basic increments. The kerning information is 1 if the 
character descends below the line, 2 if it rises above the 
letter 'a', and 3 if it both rises and descends. The kerning 
information for special characters is not used and so may 
be 0. The code is the number sent to the typesetter to 
produce the character. The second format is used to indi- 
cate that the character has more than one name. The 
double quote indicates that this name has the same values 
as the preceding line. The kerning and code fields are not 
used if the width field is a double quote character. 

Troff and its postprocessors read this information from 
binary files produced from the ASCII files by a program 
distributed with troff called makedev. For those with a 
need to know, a description of the format of these files fol- 
lows: 

The file DESC.out starts with the dev structure, defined 
by dev.h: 
/* 

dev.h: characteristics of a typesetter 
* / 



struct dev { 

short filesize; /* number of bytes in file, */ 

/* excluding dev part */ 

short res; /* basic resolution in goobies/inch */ 

short nor; /* goobies horizontally */ 

short vert; 

short unitwidth; /* size at which widths are given*/ 

short nfonts; /* number fonts physically available */ 

short nsizes; /* number of pointsizes */ 

short sizescale; /* scaling for fractional pointsizes */ 

short paperwidth; /* max line length in units */ 

short paperlength; /* max paper length in units */ 

short nchtab; /* number of funny names in chtab */ 

short lchname; /* length of chname table */ 
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short 
short 



spare 1; /* in case of expansion */ 
spare2; 



}; 



Filesize is just the size of everything in DESC.out exclud- 
ing the dev structure. Nfonts is the number of different 
font positions available. N sizes is the number of different 
pointsizes supported by this typesetter. Nchtab is the 
number of special character names. Lchname is the total 
number of characters, including nulls, needed to list all 
the special character names. At the end of the structure 
are two spares for later expansions. 

Immediately following the dev structure are a number of 
tables. First is the sizes table, which contains nsizes + 1 
shorts (a null at the end), describing the pointsizes of text 
available on this device. The second table is the 
funny charjndexjable . It contains indices into the the 
table which follows it, the funny char strings. The 
indices point to the beginning of each special character 
name which is stored in the funny _char_strings table. The 
funny _char_strings table is lchname characters long, while 
the funny _charjndexjable is nchtab shorts long. 

Following the dev structure will occur nfonts {font}. out 
files, which are used to initialize the font positions. These 
{font}. out files, which also exist as separate files, begin 
with a font structure and then are followed by four char- 
acter arrays: 
struct font { /* characteristics of a font */ 

char nwfont; /* number of width entries */ 
char specfont; /* 1 == special font */ 

char ligfont; /* 1 ligatures exist on this font */ 
char spare 1; /* unused for now */ 
char namefontllO]; /* name of this font, e.g., R */ 
char intname[10l; /* internal name of font, in ASCII */ 



The font structure tells how many defined characters there 
are in the font, whether the font is a "special" font and if 
it contains ligatures. It also has the ASCII name of the 
font, which should match the name of the file it appears 
in, and the internal name of the font on the typesetting 
device (intname). The internal name is independent of 
the font position and name that troff knows about. For 



}; 
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example, you might say mount R in position 4, but when 
asking the typesetter to actually produce a character from 
the R font, the postprocessor which instructs the typesetter 
would use intname. 

The first three character arrays are specific for the font 
and run in parallel. The first array, widths, contains the 
width of each character relative to unitwidth. Unitwidth 
is defined in DESC. The second array, kerning, contains 
kerning information. If a character rises above the letter 
'a', 02 is set. If it descends below the line, 01 is set. The 
third array, codes, contains the code that is sent to the 
typesetter to produce the character. 

The fourth array is defined by the device description in 
DESC. It is the font Jndex Jable . This table contains 
indices into the width, kerning, and code tables for each 
character. The order that characters appear in these three 
tables is arbitrary and changes from one font to the next. 
In order for troff to be able to translate from ASCII and 
the special character names to these arbitrary tables, the 
font Jndex Jable is created with an order which is con- 
stant for each device. The number of entries in this table 
is 96 plus the number of special character names for this 
device. The value 96 is 128 - 32, the number of printable 
characters in the ASCII alphabet. To determine whether 
a normal ASCII character exists, troff takes the ASCII 
value of the character, subtracts 32, and looks in the 
font Jndex Jable. If it finds a 0, the character is not 
defined in this font. If it finds anything else, that is the 
index into widths, kerning, and codes that describe that 
character. 

To look up a special character name, for example \(pl, the 
mathematical plus sign, and determine whether it appears 
in a particular font or not, the following procedure is fol- 
lowed. A counter is set to 0 and an index to a special 
character name is picked out of the counter' th position in 
the funny char Jndex Jable. A string comparision is per- 
formed between funny char strings [ 
funny char Jndex jable f counter J J and the special char- 
acter name, in our example pi, and if it matches, then 
troff refers to this character as ( 96 + counter). When it 
wants to determine whether a specific font supports this 
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character, it looks in font Judex table [(96 -^counter)], (see 
below), to see whether there is a 0, meaning the character 
does not appear in this font, or number, which is the index 
into the widths, kerning, and codes tables. 

Notice that since a value of 0 in the fontjndexjable indi- 
cates that a character does not exist, the 0th element of 
the width, kerning, and codes arrays are not used. For 
this reason the 0th element of the width array can be used 
for a special purpose, defining the width of a space for a 
font. Normally a space is denned by troff to be 1/3 of the 
width of the \(em character, but if the 0th element of the 
width array is non-zero, then that value is used for the 
width of a space. 

SEE ALSO 

troff (5). 

troff(l) in the UNIX Programmer's Manual— Volume 1: Com- 
mands and Utilities. 

FILES 

/usr/lib/font/dev{X}/DESC.out description file for photo- 
typesetter X 

/usr/lib/font/dev{X}/ {font} .out font description files for photo- 
typesetter X 
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NAME 

man — macros for formatting entries in this manual 

SYNOPSIS 

nroff —man files 

troff —man [ — rsl ] files 

DESCRIPTION 

These troff (I) macros are used to lay out the format of the entries 
of this manual. A skeleton entry may be found in the file 
/usr/man/uman/manO/skeleton. These macros are used by the 
man (I) command. 

The default page size is 8.5"xll", with a 6.5"xl0" text area; the 
—rsl option reduces these dimensions to 6"x9" and 4.75"x8.375", 
respectively; this option (which is not effective in nroff (1)) also 
reduces the default type size from 10-point to 9-point, and the 
vertical line spacing from 12-point to 10-point. The — rV2 option 
may be used to set certain parameters to values appropriate for 
certain Versatec printers: it sets the line length to 82 characters, 
the page length to 84 lines, and it inhibits underlining; this option 
should not be confused with the — Tvp option of the man (I) com- 
mand, which is available at some UNIX system sites. 

Any text argument below may be one to six "words". Double 
quotes ("") may be used to include blanks in a "word". If text is 
empty, the special treatment is applied to the next line that con- 
tains text to be printed. For example, .1 may be used to italicize a 
whole line, or .SM followed by .B to make small bold text. By 
default, hyphenation is turned off for nroff (I), but remains on for 
troff{\). 

Type font and size are reset to default values before each para- 
graph and after processing font- and size-setting macros, e.g., .1, 
.RB, .SM. Tab stops are neither used nor set by any macro except 
.DT and .TH. 

Default units for indents in are ens. When in is omitted, the pre- 
vious indent is used. This remembered indent is set to its default 
value (7.2 ens in troffiX), 5 ens in nroffthis corresponds to 0.5" in 
the default page size) by .TH, .P, and .RS, and restored by .RE. 

.TH t s c n Set the title and entry heading; t is the title, s is the 
section number, c is extra commentary, e.g., "local", 
n is new manual name. Invokes .DT (see below) . 
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.SH text Place subhead text, e.g., SYNOPSIS, here. 
.SS text Place sub-subhead text, e.g., Options, here. 
.B text Make text bold. 
.1 text Make text italic. 

.SM rex/ Make text 1 point smaller than default point size. 

.RI a b Concatenate roman a with italic b, and alternate 
these two fonts for up to six arguments. Similar mac- 
ros alternate between any two of roman, italic, and 
bold: 

.IR .RB .BR .IB .BI 

.P Begin a paragraph with normal font, point size, and 

indent. .PP is a synonym for .P. 
.HP in Begin paragraph with hanging indent. 
.TP in Begin indented paragraph with hanging tag. The next 

line that contains text to be printed is taken as the 

tag. If the tag does not fit, it is printed on a separate 

line. 

.IP t in Same as .TP in with tag /; often used to get an 
indented paragraph without a tag. 

.RS in Increase relative indent (initially zero) . Indent all 
output an extra in units from the current left margin. 

.RE k Return to the fcth relative indent level (initially, k—\; 

k=0 is equivalent to k=l); if k is omitted, return to 
the most recent lower indent level. 

.PM m Produces proprietary markings; where m may be P 
for PRIVATE, N for NOTICE, BP for BELL LABORA- 
TORIES PROPRIETARY, or BR for BELL LABORA- 
TORIES RESTRICTED. 

JDT Restore default tab settings (every 7.2 ens in troffiX), 

5 ens in nroffil)). 

.PD v Set the interparagraph distance to v vertical spaces. 

If v is omitted, set the interparagraph distance to the 
default value (0.4v in troffiX), lv in nroffiX)). 

The following strings are defined: 

\*R ® in troffiX), (Reg.) in nroff. 

\*S Change to default type size. 

\*(Tm Trademark indicator. 

The following number registers are given default values by .TH: 

IN Left margin indent relative to subheads (default is 7.2 

ens in troffiX), 5 ens in nroff i\)). 
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LL 
PD 



Line length including IN. 
Current interparagraph distance. 



CAVEATS 

In addition to the macros, strings, and number registers mentioned 
above, there are defined a number of internal macros, strings, and 
number registers. Except for names predefined by troff (l) and 
number registers d, m, and y, all such internal names are of the 
form XA, where X is one of ), 1, and }, and A stands for any 
alphanumeric character. 

If a manual entry needs to be preprocessed by eqniX) (or neqn), 
and/or tbl(l), it must begin with a special line (described in 
man(l)), causing the man command to invoke the appropriate 
preprocessor (s). 

The programs that prepare the Table of Contents and the Per- 
muted Index for this Manual assume the NAME section of each 
entry consists of a single line of input that has the following for- 
mat: 

namef, name, name ...] \— explanatory text 

The macro package increases the inter-word spaces (to eliminate 
ambiguity) in the SYNOPSIS section of each entry. 

The macro package itself uses only the roman font (so that one 
can replace, for example, the bold font by the constant-width font 
(CW). Of course, if the input text of an entry contains requests 
for other fonts (e.g., .1, .RB, \fl), the corresponding fonts must be 
mounted. 

FILES 

/usr/lib/ tmac/tmac.an 
/usr/lib/macros/cmp.n.[dt].an 
/usr/lib/macros/ucmp.n.an 
/usr/man/[uap]_man/manO/skeleton 

SEE ALSO 

eqn(l), man(l), nroff(l), tbl(l), tc(l), troff(l) in the UNIX 
Programmer's Manual —Volume 1: Commands and Utilities. 

BUGS 

If the argument to .TH contains any blanks and is not enclosed by 
double quotes (""), there will be strange irregular dots on the out- 
put. 
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NAME 

math — math functions and constants 

SYNOPSIS 

#include <math.h> 

DESCRIPTION 

This file contains declarations of all the functions in the Math 
Library (described in Section 3M), as well as various functions in 
the C Library (Section 3C) that return floating-point values. 

It defines the structure and constants used by the matherr(3M) 
error-handling mechanisms, including the following constant used 
as an error-return value: 

HUGE The maximum value of a single-precision 

floating-point number. 

The following mathematical constants are defined for user conveni- 
ence: 

M E The base of natural logarithms (e). 

M LOG2E The base-2 logarithm of e. 

M LOG 1 OE The base- 1 0 logarithm of e . 

MJLN2 The natural logarithm of 2. 

M_LN10 The natural logarithm of 10. 

M PI ir, the ratio of the circumference of a circle 

to its diameter. (There are also several 
fractions of ic, its reciprocal, and its square 
root.) 

MSQRT2 The positive square root of 2. 

M_SQRT1_2 The positive square root of 1/2. 

For the definitions of various machine-dependent "constants," see 
the description of the <values.h> header file. 



FILES 



/usr/include/math.h 



SEE ALSO 

intro(3), matherr(3M), values (5). 
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NAME 

mm — the MM macro package for formatting documents 

SYNOPSIS 

mm [ options ] [ files ] 

nroff —mm [ options ] [ files ] 

nroff —cm [ options ] [ files ] 



mmt [ options ] [ files ] 

troff —mm [ options 1 [ files ] 



DESCRIPTION 

This package provides a formatting capability for a very wide 
variety of documents. It is the standard package used by the BTL 
typing pools and documentation centers. The manner in which a 
document is typed in and edited is essentially independent of 
whether the document is to be eventually formatted at a terminal 
or is to be phototypeset. See the references below for further 
details. 

The —mm option causes nroff (I) and troff (I) to use the non- 
compacted version of the macro package, while the —cm option 
results in the use of the compacted version, thus speeding up the 
process of loading the macro package. 

FILES 

/usr/lib/tmac/tmac.m pointer to the non-compacted ver- 

sion of the package 

/usr/lib/macros/mm[nt] non-compacted version of the 

package 

/usr/lib/macros/cmp.n.[dt].m compacted version of the package 
/usr/lib/macros/ucmp.n.m initializers for the compacted ver- 
sion of the package 

SEE ALSO 

mm(l), mmt(l), nroff (1), troff (1) in the UNIX Programmer's 
Manual —Volume 1: Commands and Utilities. 
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NAME 

mosd — the OSDD adapter macro package for formatting docu- 
ments 

SYNOPSIS 

osdd [ options ] [ files ] 

mm —mosd [ options ] [ files ] 

nroff —mm —mosd [ options ] [ files ] 

nroff —cm —mosd [ options ] [ files ] 

mmt —mosd [ options ] [ files ] 
troff —mm —mosd [ options ] [ files ] 
DESCRIPTION 

The OSDD adapter macro package is a tool used in conjunction 
with the MM macro package to prepare Operations Systems 
Deliverable Documentation. Many of the OSDD Standards are 
different from the default format provided by MM. The OSDD 
adapter package sets the appropriate MM options for automatic 
production of the OSDD Standards. The OSDD adapter package 
also generates the correct OSDD page headers and footers, heading 
styles, Table of Contents format, etc. 

OSDD document (input) files are prepared with the MM macros. 
Additional information which must be given at the beginning of 
the document file is specified by the following string definitions: 

.ds HI document-number 

.ds H2 section-number 

.ds H3 issue-number 

.ds H4 date 

.ds H5 rating 

The document -number should be of the standard 10-character for- 
mat. The words "Section" and "Issue" should not be included in 
the string definitions; they will be supplied automatically when the 
document is printed. For example: 

.ds HI OPA-1P1 35-01 

.ds H2 4 

.ds H3 2 
automatically produces 

OPA-1P135-01 

Section 4 

Issue 2 
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as the document page header. Quotation marks are not used in 
string definitions. 

If certain information is not to be included in a page header, then 
the string is defined as null; e.g., 
.ds H2 

means that there is no section-number. 

The OSDD Standards require that the Table of Contents be num- 
bered beginning with Page I. By default, the first page of text 
will be numbered Page 2. If the Table of Contents has more than 
one page, for example n, then either — rPw+/ must be included as 
a command line option or .nr P n must be included in the docu- 
ment file. For example, if the Table of Contents is four pages 
then use — rP5 on the command line or .nr P 4 in the document 
file. 

The OSDD Standards require that certain information such as the 
document rating appear on the Document Index or on the Table of 
Contents page if there is no index. By default, it is assumed that 
an index has been prepared separately. If there is no index, the 
following must be included in the document file: 
.nr Di 0 

This will ensure that the necessary information is included on the 
Table of Contents page. 

The OSDD Standards require that all numbered figures be placed 
at the end of the document. The .Fg macro is used to produce full 
page figures. This macro produces a blank page with the appropri- 
ate header, footer, and figure caption. Insertion of the actual 
figure on the page is a manual operation. The macro usage is 

.Fg page-count "figure caption" 
where page -count is the number of pages required for a multi-page 
figure (default 1 page). 

The .Fg macro cannot be used within the document unless the final 
.Fg in a series of figures is followed by a .SK macro to force out 
the last figure page. 

The Table of Contents for OSDD documents (see Figure 4 in Sec- 
tion 4.1 of the OSDD Standards) is produced with: 
.Tc 

System Type 
System Name 
Document Type 
.Td 
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The .Tc/.Td macros are used instead of the .TC macro from MM. 

The .PM macro may be used to generate proprietary markings — 
see the MM document for legal styles. 

The .P macro is used for paragraphs. The Np register is set 
automatically to indicate the paragraph numbering style. It is 
very important that the .P macro be used correctly. All para- 
graphs (including those immediately following a .H macro) must 
use a .P macro. Unless there is a JP macro, there will not be a 
number generated for the paragraph. Similarly, the .P macro 
should not be used for text which is not a paragraph. The .SP 
macro may be appropriate for these cases, e.g., for "paragraphs" 
within a list item. 

The page header format is produced automatically in accordance 
with the OSDD Standards. The OSDD Adapter macro package 
uses the .TP macro for this purpose. Therefore the .TP macro nor- 
mally available in MM is not available for users. 

FILES 

/usr/lib/tmac/tmac.osd 

SEE ALSO 

mm (5). 

mm(l), mmt(l), nroff(l), troff(l) in the UNIX Programmer's 
Manual —Volume I: Commands and Utilities. 
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NAME 

mptx — the macro package for formatting a permuted index 

SYNOPSIS 

nroff —mptx [ options ] [ files ] 

troff —mptx [ options ] [ files 1 

DESCRIPTION 

This package provides a definition for the .xx macro used for for- 
matting a permuted index as produced by ptxil). This package 
does not provide any other formatting capabilities such as headers 
and footers. If these or other capabilities are required, the mptx 
macro package may be used in conjuction with the MM macro 
package. In this case, the —mptx option must be invoked after 
the —mm call. For example: 

nroff —cm —mptx file 

or 

mm —mptx file 

FILES 

/usr/lib/tmac/tmac.ptx pointer to the non-compacted version of 

the package 

/usr/lib/macros/ptx non-compacted version of the package 

SEE ALSO 

mm (5). 

mm(l), nroff(l), ptx(l), troff (l) in the UNIX Programmer's 
Manual —Volume 1: Commands and Utilities. 
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NAME 

mv — a troff macro package for typesetting viewgraphs and slides 

SYNOPSIS 

mvt [ — a ] [ options ] [ files ] 

troff [ -a ] [ -rXl ] — mv [ options ] [ files ] 

DESCRIPTION 

This package makes it easy to typeset viewgraphs and projection 
slides in a variety of sizes. A few macros (briefly described below) 
accomplish most of the formatting tasks needed in making tran- 
sparencies. All of the facilities of troff (l), eqn(l), and tbliX) are 
available for more difficult tasks. 

The output can be previewed on most terminals, and, in particular, 
on the TEKTRONIX 4014. For this device, specify the -rXl 
option (this option is automatically specified by the mvt 
command— q.v.— when that command is invoked with the — T4014 
option). To preview output on other terminals, specify the —a 
option. 

The available macros are: 

.VS [n] [/] [d] Foil-start macro; foil size is to be 7"x7"; n is 
the foil number, i is the foil identification, d is 
the date; the foil-start macro resets all param- 
eters (indent, point size, etc.) to initial default 
values, except for the values of i and d argu- 
ments inherited from a previous foil-start 
macro; it also invokes the .A macro (see 
below). 

The naming convention for this and the follow- 
ing eight macros is that the first character of 
the name (V or S) distinguishes between view- 
graphs and slides, respectively, while the 
second character indicates whether the foil is 
square (S), small wide (w), small high (h), big 
wide (W), or big high (H). Slides are "skin- 
nier" than the corresponding viewgraphs: the 
ratio of the longer dimension to the shorter 
one is larger for slides than for viewgraphs. 
As a result, slide foils can be used for view- 
graphs, but not vice versa; on the other hand, 
viewgraphs can accommodate a bit more text. 
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.Vw [n] [i] [d] Same as .VS, except that foil size is 7" wide x 
5" high. 

.Vh [n] [i] [d] Same as .VS, except that foil size is 5"x7". 

.VW In] [i] [d] Same as .VS, except that foil size is 7"x5.4". 

•VH [n] [i] [d] Same as .VS, except that foil size is 7"x9". 

.Sw [n] [i] [d] Same as .VS, except that foil size is 7"x5". 

•Sh [n] [/] [d] Same as .VS, except that foil size is 5"x7". 

.SW [«] [/] [d] Same as .VS, except that foil size is 7"x5.4". 

.SH [n] [i] [d] Same as .VS, except that foil size is 7"x9". 

.A [x] Place text that follows at the first indentation 

level (left margin); the presence of x 
suppresses the V2 line spacing from the preced- 
ing text. 

.B [m [s] ] Place text that follows at the second indenta- 
tion level; text is preceded by a mark; m is the 
mark (default is a large bullet); s is the incre- 
ment or decrement to the point size of the 
mark with respect to the prevailing point size 
(default is 0); if s is 100, it causes the point 
size of the mark to be the same as that of the 
default mark. 

.C [m [s] ] Same as .B, but for the third indentation level; 
default mark is a dash. 

.D [m [s] ] Same as .B, but for the fourth indentation 
level; default mark is a small bullet. 

.T string String is printed as an over-size, centered title. 

J [in] [a [x] ] Change the current text indent (does not 
affect titles); in is the indent (in inches unless 
dimensioned, default is 0); if in is signed, it is 
an increment or decrement; the presence of a 
invokes the .A macro (see below) and passes x 
(if any) to it. 

•S [p] [I] Set the point size and line length; p is the 

point size (default is "previous"); if p is 100, 
the point size reverts to the initial default for 
the current foil-start macro; if p is signed, it is 
an increment or decrement (default is 18 for 
.VS, .VH, and .SH, and 14 for the other foil- 
start macros); / is the line length (in inches 
unless dimensioned; default is 4.2" for .Vh, 
3.8" for .Sh, 5" for .SH, and 6" for the other 
foil-start macros). 
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.DF n f [n / ...] Define font positions; may not appear within a 
foil's input text (i.e., it may only appear after 
all the input text for a foil, but before the next 
foil-start macro); n is the position of font /; up 
to four "« /" pairs may be specified; the first 
font named becomes the prevailing font; the 
initial setting is (H is a synonym for G): 
.DF 1 H 2 I 3 B 4 S 

.DV [a] [b] [c] [d] Alter the vertical spacing between indentation 
levels; a is the spacing for .A, b is for .B, c is 
for .C, and d is for .D; all non-null arguments 
must be dimensioned; null arguments leave the 
corresponding spacing unaffected; initial set- 
ting is: 

.DV .5v .5v .5v Ov 

.U strl [str2] Underline strl and concatenate str2 (if any) 
to it. 

The last four macros in the above list do not cause a break; the .1 
macro causes a break only if it is invoked with more than one 
argument; all the other macros cause a break. 

The macro package also recognizes the following upper-case 
synonyms for the corresponding lower-case troff requests: 

.AD .BR .CE .FI .HY .NA .NF .NH .NX .SO .SP 
.TA .TI 

The Tm string produces the trademark symbol. 

The input tilde (") character is translated into a blank on output. 

See the user's manual cited below for further details. 

FILES 

/usr/lib/tmac/tmac.v 
/usr/lib/macros/vmca 

SEE ALSO 

eqn(l), mmt(l), tbl(l), troff(l) in the UNIX Programmer's 
Manual —Volume 1: Commands and Utilities. 

BUGS 

The .VW and .SW foils are meant to be 9" wide by 7" high, but 
because the typesetter paper is generally only 8" wide, they are 
printed 7" wide by 5.4" high and have to be enlarged by a factor 
of 9/7 before use as viewgraphs; this makes them less than totally 
useful. 
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NAME 

prof — profile within a function 

SYNOPSIS 

#define MARK 
#include <prof.h> 

void MARK (name) 

DESCRIPTION 

MARK will introduce a mark called name that will be treated the 
same as a function entry point. Execution of the mark will add to 
a counter for that mark, and program-counter time spent will be 
accounted to the immediately preceding mark or to the function if 
there are no preceding marks within the active function. 

Name may be any combination of up to six letters, numbers or 
underscores. Each name in a single compilation must be unique, 
but may be the same as any ordinary program symbol. 

For marks to be effective, the symbol MARK must be defined 
before the header file <prof.h> is included. This may be defined 
by a preprocessor directive as in the synopsis, or by a command 
line argument, i.e: 

cc -p — DMARK foo.c 

If MARK is not defined, the MARK (name) statements may be left 
in the source files containing them and will be ignored. 

EXAMPLE 

In this example, marks can be used to determine how much time is 
spent in each loop. Unless this example is compiled with MARK 
defined on the command line, the marks are ignored. 

#include <prof.h> 

foo( ) 
{ 

int i, j; 



MARK(loopl); 

for (i - 0; i < 2000; i++) { 
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} 

MARK(loop2); 

for (j = 0; j < 2000; j++) { 
} 

} 

SEE ALSO 

profil(2), monitor (3C). 

prof(l) in the UNIX Programmer's Manual— Volume 1: Com- 
mands and Utilities. 
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NAME 

regexp — regular expression compile and match routines 
SYNOPSIS 

#define INIT < declarations > 
#define GETCO <getc code> 
#define PEEKCO <peekc code> 
#define UNGETC(c) <ungetc code> 
#define RETURN (pointer) < return code> 
#define ERROR (val) <error code> 

#include <regexp.h> 

char *compile (instring, expbuf, endbuf, eof) 
char *instring, *expbuf, *endbuf; 
int eof; 

int step (string, expbuf) 
char *string, *expbuf; 

extern char *locl, *loc2, *locs; 

extern int circf, sed, nbra; 

DESCRIPTION 

This page describes general-purpose regular expression matching 
routines in the form of ed(l), defined in /usr/include/regexp.h. 
Programs such as ed(l), sedil), grep(l), bs(l), expr(l), etc., 
which perform regular expression matching use this source file. In 
this way, only this file need be changed to maintain regular expres- 
sion compatibility. 

The interface to this file is unpleasantly complex. Programs that 
include this file must have the following five macros declared 
before the "#include <regexp.h>" statement. These macros are 
used by the compile routine. 

GETCO Return the value of the next character in 

the regular expression pattern. Successive 
calls to GETCO should return successive 
characters of the regular expression. 

PEEKCO Return the next character in the regular 

expression. Successive calls to PEEKCO 
should return the same character (which 
should also be the next character returned 
by GETCO). 
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UNGETC(c) Cause the argument c to be returned by 

the next call to GETCO (and PEEKCO). 
No more that one character of pushback is 
ever needed and this character is 
guaranteed to be the last character read by 
GETCO. The value of the macro 
UNGETC(c) is always ignored. 

RETURN {pointer) This macro is used on normal exit of the 



compile routine. The value of the argu- 
ment pointer is a pointer to the character 
after the last character of the compiled reg- 
ular expression. This is useful to programs 
which have memory allocation to manage. 

ERROR (val) This is the abnormal return from the com - 

pile routine. The argument val is an error 
number (see table below for meanings). 
This call should never return. 

ERROR MEANING 

1 1 Range endpoint too large. 

16 Bad number. 

25 "\digit" out of range. 

36 Illegal or missing delimiter. 

41 No remembered search string. 

42 \( \) imbalance. 

43 Too many \(. 

44 More than 2 numbers given in \{ \}. 

45 } expected after \. 

46 First number exceeds second in \{ \). 

49 I 1 imbalance. 

50 Regular expression overflow. 



The syntax of the compile routine is as follows: 

compile (instring, expbuf, endbuf, eof) 

The first parameter instring is never used explicitly by the compile 
routine but is useful for programs that pass down different pointers 
to input characters. It is sometimes used in the INIT declaration 
(see below). Programs which call functions to input characters or 
have characters in an external array can pass down a value of 
((char *) 0) for this parameter. 
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The next parameter expbuf is a character pointer. It points to the 
place where the compiled regular expression will be placed. 

The parameter endbuf is one more than the highest address where 
the compiled regular expression may be placed. If the compiled 
expression cannot fit in {endbuf— expbuf) bytes, a call to 
ERROR (50) is made. 

The parameter eof is the character which marks the end of the 
regular expression. For example, in ed(l), this character is usu- 
ally a /. 

Each program that includes this file must have a #define statement 
for INIT. This definition will be placed right after the declaration 
for the function compile and the opening curly brace ({). It is 
used for dependent declarations and initializations. Most often it 
is used to set a register variable to point the beginning of the regu- 
lar expression so that this register variable can be used in the 
declarations for GETCQ, PEEKCO and UNGETCO. Otherwise it 
can be used to declare external variables that might be used by 
GETCO, PEEKCO and UNGETCO. See the example below of 
the declarations taken from grepil). 

There are other functions in this file which perform actual regular 
expression matching, one of which is the function step. The call to 
step is as follows: 

step (string, expbuf) 

The first parameter to step is a pointer to a string of characters to 
be checked for a match. This string should be null terminated. 

The second parameter expbuf is the compiled regular expression 
which was obtained by a call of the function compile. 

The function step returns non-zero if the given string matches the 
regular expression, and zero if the expressions do not match. If 
there is a match, two external character pointers are set as a side 
effect to the call to step. The variable set in step is loci. This is 
a pointer to the first character that matched the regular expres- 
sion. The variable loc2 y which is set by the function advance, 
points to the character after the last character that matches the 
regular expression. Thus if the regular expression matches the 
entire line, loci will point to the first character of string and loc2 
will point to the null at the end of string. 

Step uses the external variable circf which is set by compile if the 
regular expression begins with A . If this is set then step will try to 
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match the regular expression to the beginning of the string only. 
If more than one regular expression is to be compiled before the 
first is executed the value of circf should be saved for each com- 
piled expression and circf should be set to that saved value before 
each call to step. 

The function advance is called from step with the same arguments 
as step. The purpose of step is to step through the string argu- 
ment and call advance until advance returns non-zero indicating a 
match or until the end of string is reached. If one wants to con- 
strain string to the beginning of the line in all cases, step need not 
be called; simply call advance. 

When advance encounters a * or \{ \) sequence in the regular 
expression, it will advance its pointer to the string to be matched 
as far as possible and will recursively call itself trying to match the 
rest of the string to the rest of the regular expression. As long as 
there is no match, advance will back up along the string until it 
finds a match or reaches the point in the string that initially 
matched the * or \{ \}. It is sometimes desirable to stop this back- 
ing up before the initial point in the string is reached. If the 
external character pointer Iocs is equal to the point in the string at 
sometime during the backing up process, advance will break out of 
the loop that backs up and will return zero. This is used by ed(l) 
and sediX) for substitutions done globally (not just the first 
occurrence, but the whole line) so, for example, expressions like 
s/y*//g do not loop forever. 

The additional external variables sed and nbra are used for special 
purposes. 



The following is an example of how the regular expression macros 
and calls look from grep(l): 



EXAMPLES 



#define INIT 
#define GETCO 
#define PEEKCO 



#define UNGETC(c) 
#define RETURN (c) 
#define ERROR (c) 



register char *sp = instring; 

(*sp++) 

(*sp) 

(— sp) 



return; 
regerrO 



#include <regexp.h> 



(void) compile (*argv, expbuf, &expbuf[ESIZE], \0'); 
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if (stepOinebuf, expbuf)) 

succeedO; 

FILES 

/usr/include/regexp.h 
SEE ALSO 

bs(l), ed(l), expr(l), grep(l), sed(l) in the UNIX Programmer's 
Manual —Volume 1: Commands and Utilities. 

BUGS 

The handling of circf is kludgy. 

The actual code is probably easier to understand than this manual 
page. 
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NAME 

stat — data returned by stat system call 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/stat.h> 

DESCRIPTION 

The system calls stat and fstat return data whose structure is 
defined by this include file. The encoding of the field stjnode is 
defined in this file also. 

/* 

* Structure of the result of stat 
*/ 



stat 




devt 


stjdev; 


inot 


stino; 


ushort 


stmode; 


short 


stjilink; 


ushort 


st_uid; 


ushort 


st jgid; 


dev_t 


strdev; 


off_t 


st_size; 


timet 


st_atime; 


timet 


stmtime; 


timet 


stctime; 



}; 



#define 


SIFMT 


0170000 


/* 


type of file */ 


#define 


SJFDIR 


0040000 


/* 


directory */ 


#define 


SJFCHR 


0020000 


/* 


character special */ 


#define 


SIFBLK 


0060000 


/* 


block special */ 


#define 


SIFREG 


0100000 


/* 


regular */ 


#define 


SJFIFO 


0010000 


/* 


fifo*/ 


#define 


SJSUID 


04000 


/* 


set user id on execution */ 


#define 


SJSGID 


02000 


/* 


set group id on execution */ 


#define 


SJSVTX 


01000 


/* 


save swapped text */ 


#define 


SIREAD 


00400 


/* 


read permission, owner */ 


#define 


SJWRITE 00200 


/* 


write permission, owner */ 


#define 


SJEXEC 


00100 


/* 


exec/search permission, owner */ 
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FILES 

/usr/include/ sys/ types.h 
/usr/include/sys/ stat.h 

SEE ALSO 

stat (2), types (5). 
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NAME 



term — conventional names for terminals 



DESCRIPTION 

These names are used by certain commands (e.g., tabs (I), man{\) 
and are maintained as part of the shell environment (see sh{\), 
profile (4), and environ(5)) in the variable $TERM: 

1520 Datamedia 1520 

1620 DIABLO 1620/others using the HyType II printer 

1620—12 same, in 12-pitch mode 

2621 Hewlett-Packard 2621 series 

2631 Hewlett-Packard 2631 line printer 

2631— c Hewlett-Packard 2631 line printer - compressed mode 

2631— e Hewlett-Packard 2631 line printer - expanded mode 

2640 Hewlett-Packard 2640 series 

2645 Hewlett-Packard 264n series (other than the 2640 series) 

300 DASI/DTC/GSI 300 and others using the HyType I printer 

300—12 same, in 12-pitch mode 

300s DASI/DTC/GSI 300s 

382 DTC 382 

300s— 12 same, in 12-pitch mode 

3045 Datamedia 3045 

33 TELETYPE® Model 33 KSR 

37 TELETYPE Model 37 KSR 

40-2 TELETYPE Model 40/2 

40-4 TELETYPE Model 40/4 

4540 TELETYPE Model 4540 

3270 IBM Model 3270 

4000a Trendata 4000a 

40 1 4 TEKTRONIX 40 1 4 

43 TELETYPE Model 43 KSR 

450 DASI 450 (same as Diablo 1620) 

450—12 same, in 12-pitch mode 

735 Texas Instruments TI735 and TI725 

745 Texas Instruments TI745 

dumb generic name for terminals that lack reverse 

line-feed and other special escape sequences 

sync generic name for synchronous TELETYPE 

4540-compatible terminals 

hp Hewlett-Packard (same as 2645) 
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lp generic name for a line printer 

tnl200 User Electric TermiNet 1200 
tn300 User Electric TermiNet 300 

Up to 8 characters, chosen from [— a— zO— 9], make up a basic ter- 
minal name. Terminal sub-models and operational modes are dis- 
tinguished by suffixes beginning with a — . Names should gen- 
erally be based on original vendors, rather than local distributors. 
A terminal acquired from one vendor should not have more than 
one distinct basic name. 

Commands whose behavior depends on the type of terminal should 
accept arguments of the form —Tterm where term is one of the 
names given above; if no such argument is present, such commands 
should obtain the terminal type from the environment variable 
$TERM, which, in turn, should contain term. 

SEE ALSO 

profile (4), environ (5). 

man(l), mm(l), nroff(l), tplot(lG), sh(l), stty(l), tabs(l) in the 
UNIX Programmer's Manual —Volume 1: Commands and Utili- 
ties. 

BUGS 

This is a small candle trying to illuminate a large, dark problem. 
Programs that ought to adhere to this nomenclature do so some- 
what fitfully. 
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NAME 

troff — description of output language 
DESCRIPTION 

The device-independent troff outputs a pure ASCII description of 
a typeset document. The description specifies the typesetting dev- 
ice, the fonts, and the point sizes of characters to be used as well 
as the position of each character on the page. A list of all the 
legal commands follows. Most numbers are denoted as n and are 
ASCII strings. Strings inside of I 1 are optional. Troff may pro- 
duce them, but they are not required for the specification of the 
language. The character \n has the standard meaning of "newline" 
character. Between commands white space has no meaning. 
White space characters are spaces and newlines. All commands 
which have an arbitary length numerical parameter or word must 
be followed by white space. For example, the command to specify 
point size, s###, must be followed by a space or newline. 

sn The point size of the characters to be gen- 

erated. 

fn The font mounted in the specified position 

is to be used. The number ranges from 0 
to the highest font presently mounted. 0 is 
a special position, invoked by troff, but not 
directly accessible to the troff user. Nor- 
mally fonts are mounted starting at position 
1. 

cx Generate the character x at the current 

location on the page; x is a single ASCII 
character. 

Cxyz Generate the special character xyz. The 

name of the character is delimited by white 
space. The name will be one of the special 
characters legal for the typesetting device 
as specified by the device specification 
found in the file DESC. This file resides in 
a directory specific for the typesetting dev- 
ice. (See font (5) and /usr/lib/font/dev*.) 

H« Change the horizonal position on the page 

to the number specified. The number is in 
basic units of motions as specified by 
DESC. This is an absolute "goto". 
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hn Add the number specified to the current 

horizontal position. This is a relative 
"goto". 

V« Change the vertical position on the page to 

the number specified (down is positive) . 

vn Add the number specified to the current 

vertical position. 

nnx This is a two-digit number followed by an 

ASCII character. The meaning is a combi- 
nation of h/i followed by ex. The two digits 
nn are added to the current horizontal posi- 
tion and then the ASCII character, x, is 
produced. This is the most common form 
of character specification. 

nb a This command indicates that the end of a 

line has been reached. No action is 
required, though by convention the horizon- 
tal position is set to 0. Troff will specify a 
resetting of the x,y coordinates on the page 
before requesting that more characters be 
printed. The first number, b, is the amount 
of space before the line and the second 
number, a, the amount of space after the 
line. The second number is delimited by 
white space. 

w Aw appears between words of the input 

document. No action is required. It is 
included so that one device can be emulated 
more easily on another device. 

pn Begin a new page. The new page number 

is included in this command. The vertical 
position on the page should be set to 0. 

{ Push the current environment, which means 

saving the current point size, font, and 
location on the page. 

} Pop a saved environment. 

txxxxx Print the string of characters, xxxxx, using 

the natural width of each character to 
determine the next x coordinate. Troff 
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# .... \n 
Dl x y\n 

Dc d\n 
De dx dy\n 

Da x y r\n 

D" x y x y...\n 

x i[nitl\n 

x T device\n 
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does not currently produce this form of 
command. It is not recommended. The 
characters will probably be too close 
together. 

A line beginning with a pound sign is a 
comment. 

Draw a line from the current location to 
x,y. At the end of the drawing operation 
the current location will be x,y. 

Draw a circle of diameter d with the left- 
most edge being at the current location (x, 
y). The current location after drawing the 
circle will be x+d,y, the rightmost edge of 
the circle. 

Draw an ellipse with the specified axes, dx 
is the axis in the x direction and dy is the 
axis in the y direction. The leftmost edge 
of the ellipse will be at the current location. 
After drawing the ellipse the current loca- 
tion will be x+dx,y. 

Draw a counterclockwise arc from the 
current location to x,y using a circle of 
radius r . The current location after draw- 
ing the arc will be x,y. 

Draw a spline curve (wiggly line) between 
each of the x,y coordinate pairs starting at 
the current location. The final location will 
be the final x,y pair of the list. Currently 
there may be no more than 36 x,y pairs to 
this command. 

Initialize the typesetting device. The 
actions required are dependent on the dev- 
ice. An ink command will always occur 
before any output generation is attempted. 

The name of the typesetter is device. This 
is the same as the argument to the — T 
option. The information about the 
typesetter will be found in the directory 
/usr/lib/font/devWmce} . 
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x rfesl n h v\n 



x p[ause]\n 
x s[top]\n 

x t[railerl\n 

x ftont] n name\n 
x Hleight] «\n 

x SUantl «\n 



The resolution of the typesetting device in 
increments per inch is n. Motion in the 
horizontal direction can take place in units 
of h basic increments. Motion in the verti- 
cal direction can take place in units of v 
basic increments. For example, the APS-5 
typesetter has a basic resolution of 723 
increments per inch and can move in either 
direction in 723rds of an inch. Its 
specification is: 
x res 723 1 1 

Pause. Cause the current page to finish but 
do not relinquish the typesetter. 

Stop. Cause the current page to finish and 
then relinquish the typesetter. Perform any 
shutdown and bookkeeping procedures 
required. 

Generate a trailer. On some devices no 
operation is performed. 

Load the font name into position n. 

Set the character height to n points. This 
causes the letters to be elongated or shor- 
tened. It does not affect the width of a 
letter. 

Set the slant to n degrees. Only some 
typesetters can do this and not all angles 
are supported. 
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NAME 



types — primitive system data types 

SYNOPSIS 

#include <sys/types.h> 

DESCRIPTION 

The data types defined in the include file are used in UNIX system 
code; some data of these types are accessible to user code: 



The form daddrj is used for disk addresses except in an i-node on 
disk, see fs(4). Times are encoded in seconds since 00:00:00 GMT, 
January 1, 1970. The major and minor parts of a device code 
specify kind and unit number of a device and are installation- 
dependent. Offsets are measured in bytes from the beginning of a 
file. The label J variables are used to save the processor state 
while another process is running. 



typedef struct { int r[l]; } * 

typedef long daddr t; 

typedef char * caddr t; 

typedef unsigned int uint; 

typedef unsigned short ushort; 

typedef ushort ino t; 

typedef short cnt_t; 

typedef long time_t; 

typedef int label_t[10]; 

typedef short dev t; 

typedef long off t; 

typedef long paddr_t; 

typedef long key_t; 



physadr; 



SEE ALSO 

fs(4). 
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NAME 

values — machine-dependent values 

SYNOPSIS 

#include <values.h> 

DESCRIPTION 

This file contains a set of manifest constants, conditionally defined 
for particular processor architectures. 

The model assumed for integers is binary representation (one's or 
two's complement), where the sign is represented by the value of 
the high-order bit. 



BYTSitype) 



HIBITS 



HIBITL 



HIBITI 



MAXSHORT 



MAXLONG 



MAXINT 



The number of bits in a specified type (e.g., 
int). 

The value of a short integer with only the 
high-order bit set (in most implementa- 
tions, 0x8000). 

The value of a long integer with only the 
high-order bit set (in most implementa- 
tions, 0x80000000). 

The value of a regular integer with only the 
high-order bit set (usually the same as 
HIBITS or HIBITL). 

The maximum value of a signed short 
integer (in most implementations, 0x7 FFF 
= 32767). 

The maximum value of a signed long 
integer (in most implementations, 
0x7FFFFFFF = 2147483647). 

The maximum value of a signed regular 
integer (usually the same as MAXSHORT 
or MAXLONG). 



MAXFLOAT, LN MAXFLOAT 



The maximum value of a 

single-precision floating-point 

number, and its natural loga- 
rithm. 
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MAXDOUBLE, LN_MAXDOUBLE The maximum value of a 

double-precision floating-point 
number, and its natural loga- 
rithm. 

MINFLOAT, LN MINFLOAT The minimum positive value of 

a single-precision floating-point 
number, and its natural loga- 
rithm. 

MINDOUBLE, LN MINDOUBLE The minimum positive value of 

a double-precision floating-point 
number, and its natural loga- 
rithm. 

FSIGNIF The number of significant bits in the 

mantissa of a single-precision floating-point 
number. 

DSIGNIF The number of significant bits in the 

mantissa of a double-precision floating- 
point number. 

FILES 

/usr/include/values.h 

SEE ALSO 

intro(3), math (5). 
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NAME 

varargs — handle variable argument list 

SYNOPSIS 

#include <varargs.h> 

vaalist 

va_dcl 

void vastart(pvar) 
va_Iist pvar; 

type va_arg(pvar, type) 
va_list pvar; 

void va_end(pvar) 
va_list pvar; 

DESCRIPTION 

This set of macros allows portable procedures that accept variable 
argument lists to be written. Routines that have variable argu- 
ment lists (such as printf(3S)) but do not use varargs are 
inherently nonportable, as different machines use different 
argument-passing conventions. 

va alist is used as the parameter list in a function header. 

va_dcl is a declaration for va_alist. No semicolon should follow 
vadcl. 

va_list is a type defined for the variable used to traverse the list. 

va_start is called to initialize pvar to the beginning of the list. 

va_arg will return the next argument in the list pointed to by pvar. 
Type is the type the argument is expected to be. Different types 
can be mixed, but it is up to the routine to know what type of 
argument is expected, as it cannot be determined at runtime. 

va_end is used to clean up. 

Multiple traversals, each bracketed by vajtart ... va end, are pos- 
sible. 

SEE ALSO 

exec (2), printf(3S). 
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EXAMPLE 

This example is a possible implementation of execl(2). 

#include <varargs.h> 
#define MAXARGS 100 

/* execl is called by 

execKfile, argl, arg2, (char *)0); 

*/ 

execl (vaalist) 

vadcl 

{ 

va list ap; 
char *file; 

char *args[MAXARGSl; 
int argno — 0; 

vastart(ap); 

file — va_arg(ap, char *); 

while ((args[argno++] =" va_arg(ap, char *)) != (char *)0) 

va_end(ap); 

return execv(file, args); 

} 

BUGS 

It is up to the calling routine to specify how many arguments there 
are, since it is not always possible to determine this from the stack 
frame. For example, execl is passed a zero pointer to signal the 
end of the list. Print/ can tell how many arguments are there by 
the format. 

It is non-portable to specify a second argument of char, short, or 
float to va_arg, since arguments seen by the called function are 
not char, short, or float. C converts char and short arguments to 
int and converts float arguments to double before passing them to 
a function. 
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